docs: 添加Spanish Diary项目部署方案

2026-08-01 21:07:21 +08:00
parent 0120d799a5
commit 9884043371
1 changed files with 373 additions and 0 deletions
@@ -0,0 +1,373 @@
 # Spanish Diary 项目部署方案
 ## 1. 部署架构
 `spanish-diary` 由前端静态页面和 Flask 后端组成，后端同时负责 API 和静态页面托管，因此只需要把 Python 服务跑起来即可。
 推荐生产部署方式：
 ```text
 Ubuntu + Python venv + Gunicorn + systemd + Nginx
 ```
 不依赖 Docker，避免国内服务器无法拉取 Docker Hub 镜像的问题。
 ## 2. 项目目录说明
 ```text
 /opt/spanish-diary
 ├── index.html            # 主页面
 ├── login.html            # 登录/注册
 ├── admin.html            # 管理员用户管理
 ├── knowledge.html        # 知识库首页
 ├── knowledge/            # 知识库分类页面
 ├── app.js                # 前端应用逻辑
 ├── api.js                # 后端 API 客户端
 ├── server/               # Flask 后端
 │   ├── app.py            # 应用入口
 │   ├── requirements.txt  # Python 依赖
 │   ├── db.py             # SQLite 初始化
 │   └── data/             # SQLite 数据库目录
 └── venv/                 # Python 虚拟环境
 ```
 SQLite 数据库路径：
 ```text
 /opt/spanish-diary/server/data/spanish_diary.db
 ```
 首次启动时后端会自动创建数据库、数据表和管理员账号。
 ## 3. Windows 本地运行
 Windows PowerShell：
 ```powershell
 cd C:\Users\Administrator\Documents\Codex\2026-07-30\build-web-apps-plugin-build-web\spanish-diary
 python -m venv .venv
 .\.venv\Scripts\Activate.ps1
 python -m pip install -r server\requirements.txt
 python server\app.py
 ```
 访问：
 ```text
 http://localhost:5000
 ```
 默认管理员：
 ```text
 用户名：admin
 密码：admin123
 ```
 ## 4. Ubuntu 生产部署
 ### 4.1 安装基础软件
 ```bash
 sudo apt update
 sudo apt install -y git python3-venv python3-pip nginx
 ```
 ### 4.2 创建运行用户并拉取代码
 ```bash
 sudo useradd --system --no-create-home --home /opt/spanish-diary --shell /usr/sbin/nologin spanish-diary || true
 sudo mkdir -p /opt/spanish-diary
 sudo git clone https://git.youzhilian.cn/guoqingshan/spanish-diary.git /opt/spanish-diary
 ```
 如果仓库是私有的，在服务器上使用 Gitea Access Token 作为密码，或配置 SSH Key。不要把令牌长期写入 shell 历史。
 ### 4.3 创建 Python 虚拟环境
 ```bash
 cd /opt/spanish-diary
 sudo python3 -m venv venv
 sudo venv/bin/pip install --upgrade pip
 sudo venv/bin/pip install -r server/requirements.txt
 sudo venv/bin/pip install gunicorn
 sudo chown -R spanish-diary:spanish-diary /opt/spanish-diary
 ```
 ### 4.4 生成 SECRET_KEY
 ```bash
 python3 -c "import secrets; print(secrets.token_hex(32))"
 ```
 把输出保存下来，后面写入 systemd 服务。
 ### 4.5 手动测试启动
 ```bash
 cd /opt/spanish-diary
 sudo -u spanish-diary env SECRET_KEY='替换为生成的密钥' \
  /opt/spanish-diary/venv/bin/gunicorn \
  --workers 2 --threads 2 \
  --bind 127.0.0.1:5000 \
  server.app:app
 ```
 另开一个终端验证：
 ```bash
 curl http://127.0.0.1:5000/
 ```
 ### 4.6 创建 systemd 服务
 ```bash
 sudo tee /etc/systemd/system/spanish-diary.service > /dev/null <<'EOF'
 [Unit]
 Description=Spanish Diary Flask App
 After=network.target
 [Service]
 User=spanish-diary
 Group=spanish-diary
 WorkingDirectory=/opt/spanish-diary
 Environment=SECRET_KEY=替换为生成的密钥
 Environment=COOKIE_SECURE=0
 Environment=PYTHONUNBUFFERED=1
 ExecStart=/opt/spanish-diary/venv/bin/gunicorn --workers 2 --threads 2 --bind 127.0.0.1:5000 server.app:app
 Restart=always
 RestartSec=3
 [Install]
 WantedBy=multi-user.target
 EOF
 sudo systemctl daemon-reload
 sudo systemctl enable --now spanish-diary
 sudo systemctl status spanish-diary
 ```
 查看日志：
 ```bash
 sudo journalctl -u spanish-diary -f
 ```
 常用命令：
 ```bash
 sudo systemctl start spanish-diary
 sudo systemctl stop spanish-diary
 sudo systemctl restart spanish-diary
 ```
 ### 4.7 配置 Nginx 反向代理
 ```bash
 sudo tee /etc/nginx/sites-available/spanish-diary > /dev/null <<'EOF'
 server {
    listen 80;
    server_name your-domain.com;
    client_max_body_size 2m;
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 EOF
 sudo ln -s /etc/nginx/sites-available/spanish-diary /etc/nginx/sites-enabled/
 sudo nginx -t
 sudo systemctl reload nginx
 ```
 没有域名时，可以先把 `server_name` 改为 `_`，使用服务器 IP 访问。
 ### 4.8 配置 HTTPS
 ```bash
 sudo apt install -y certbot python3-certbot-nginx
 sudo certbot --nginx -d your-domain.com
 ```
 启用 HTTPS 后，把 systemd 服务中的环境变量改为：
 ```ini
 Environment=COOKIE_SECURE=1
 ```
 然后重启：
 ```bash
 sudo systemctl daemon-reload
 sudo systemctl restart spanish-diary
 ```
 ### 4.9 配置防火墙
 ```bash
 sudo ufw allow OpenSSH
 sudo ufw allow 80/tcp
 sudo ufw allow 443/tcp
 sudo ufw enable
 ```
 ## 5. 数据库备份与恢复
 ### 5.1 备份
 ```bash
 sudo mkdir -p /backup
 sudo systemctl stop spanish-diary
 sudo cp /opt/spanish-diary/server/data/spanish_diary.db /backup/spanish-diary-$(date +%F).db
 sudo systemctl start spanish-diary
 ```
 建议把 `/backup` 同步到其他服务器、对象存储或本机。
 ### 5.2 恢复
 ```bash
 sudo systemctl stop spanish-diary
 sudo cp /backup/spanish-diary-YYYY-MM-DD.db /opt/spanish-diary/server/data/spanish_diary.db
 sudo chown spanish-diary:spanish-diary /opt/spanish-diary/server/data/spanish_diary.db
 sudo systemctl start spanish-diary
 ```
 ## 6. 升级项目
 ```bash
 sudo -u spanish-diary git -C /opt/spanish-diary pull origin master
 sudo systemctl restart spanish-diary
 ```
 升级前建议先备份数据库。
 ## 7. 修改默认管理员密码
 项目当前没有管理员修改密码页面，生产环境首次启动后建议手动修改 `admin` 密码。
 ```bash
 cd /opt/spanish-diary
 sudo -u spanish-diary venv/bin/python - <<'EOF'
 import sqlite3
 from werkzeug.security import generate_password_hash
 conn = sqlite3.connect("server/data/spanish_diary.db")
 conn.execute(
    "UPDATE users SET password_hash=? WHERE username='admin'",
    (generate_password_hash("你的新密码"),),
 )
 conn.commit()
 conn.close()
 print("admin password updated")
 EOF
 ```
 ## 8. 接入翻译服务
 项目支持三种翻译方式：
 - 本地词典：前端完成，无需额外服务
 - MyMemory：免费在线接口，无需部署
 - 自定义接口：可对接自建 LibreTranslate
 如果使用 LibreTranslate，请先参考百科中的《LibreTranslate Conda 部署方案（Ubuntu）》。
 在项目“翻译设置”中选择“自定义接口”：
 ```text
 接口地址：http://127.0.0.1:5001/translate
 接口密钥：你的APIKey
 ```
 扩展配置：
 ```json
 {
  "result_key": "translatedText",
  "headers": {
    "Authorization": "Bearer 你的APIKey"
  }
 }
 ```
 ## 9. 环境变量说明
 ```text
 SECRET_KEY        会话加密密钥，必须设置为随机长字符串
 COOKIE_SECURE     使用 HTTPS 时设置为 1
 PYTHONUNBUFFERED  设置为 1，便于日志实时输出
 ```
 ## 10. 常见问题
 ### 10.1 服务启动失败
 查看日志：
 ```bash
 sudo journalctl -u spanish-diary -e
 ```
 检查代码目录和数据库目录权限：
 ```bash
 sudo chown -R spanish-diary:spanish-diary /opt/spanish-diary
 sudo systemctl restart spanish-diary
 ```
 ### 10.2 Gunicorn 找不到 server.app
 确保工作目录是项目根目录：
 ```bash
 cd /opt/spanish-diary
 ```
 ### 10.3 登录后会话失效
 确认 `SECRET_KEY` 已设置，并且没有频繁更换。
 ### 10.4 HTTPS 下无法登录或会话不稳定
 确认 systemd 中已设置：
 ```ini
 Environment=COOKIE_SECURE=1
 ```
 ### 10.5 端口 5000 被占用
 修改 Gunicorn 绑定端口：
 ```bash
 --bind 127.0.0.1:5001
 ```
 同时修改 Nginx 的 `proxy_pass`：
 ```nginx
 proxy_pass http://127.0.0.1:5001;
 ```
 ## 11. 部署完成检查
 ```bash
 curl http://127.0.0.1:5000/
 sudo systemctl is-active spanish-diary
 sudo nginx -t
 ```
 浏览器访问：
 ```text
 http://your-domain.com
 ```
 使用默认管理员登录后，应立即修改管理员密码。