Clone
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Spanish Diary 项目部署方案
1. 部署架构
spanish-diary 由前端静态页面和 Flask 后端组成，后端同时负责 API 和静态页面托管，因此只需要把 Python 服务跑起来即可。
推荐生产部署方式：
Ubuntu + Python venv + Gunicorn + systemd + Nginx
不依赖 Docker，避免国内服务器无法拉取 Docker Hub 镜像的问题。
2. 项目目录说明
/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 数据库路径：
/opt/spanish-diary/server/data/spanish_diary.db
首次启动时后端会自动创建数据库、数据表和管理员账号。
3. Windows 本地运行
Windows 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
访问：
http://localhost:5000
默认管理员：
用户名：admin
密码：admin123
4. Ubuntu 生产部署
4.1 安装基础软件
sudo apt update
sudo apt install -y git python3-venv python3-pip nginx
4.2 创建运行用户并拉取代码
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 虚拟环境
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
python3 -c "import secrets; print(secrets.token_hex(32))"
把输出保存下来，后面写入 systemd 服务。
4.5 手动测试启动
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
另开一个终端验证：
curl http://127.0.0.1:5000/
4.6 创建 systemd 服务
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
查看日志：
sudo journalctl -u spanish-diary -f
常用命令：
sudo systemctl start spanish-diary
sudo systemctl stop spanish-diary
sudo systemctl restart spanish-diary
4.7 配置 Nginx 反向代理
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
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
启用 HTTPS 后，把 systemd 服务中的环境变量改为：
Environment=COOKIE_SECURE=1
然后重启：
sudo systemctl daemon-reload
sudo systemctl restart spanish-diary
4.9 配置防火墙
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
5. 数据库备份与恢复
5.1 备份
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 恢复
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. 升级项目
sudo -u spanish-diary git -C /opt/spanish-diary pull origin master
sudo systemctl restart spanish-diary
升级前建议先备份数据库。
7. 修改默认管理员密码
项目当前没有管理员修改密码页面，生产环境首次启动后建议手动修改 admin 密码。
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）》。
在项目“翻译设置”中选择“自定义接口”：
接口地址：http://127.0.0.1:5001/translate
接口密钥：你的APIKey
扩展配置：
{
"result_key": "translatedText",
"headers": {
"Authorization": "Bearer 你的APIKey"
}
}
9. 环境变量说明
SECRET_KEY 会话加密密钥，必须设置为随机长字符串
COOKIE_SECURE 使用 HTTPS 时设置为 1
PYTHONUNBUFFERED 设置为 1，便于日志实时输出
10. 常见问题
10.1 服务启动失败
查看日志：
sudo journalctl -u spanish-diary -e
检查代码目录和数据库目录权限：
sudo chown -R spanish-diary:spanish-diary /opt/spanish-diary
sudo systemctl restart spanish-diary
10.2 Gunicorn 找不到 server.app
确保工作目录是项目根目录：
cd /opt/spanish-diary
10.3 登录后会话失效
确认 SECRET_KEY 已设置，并且没有频繁更换。
10.4 HTTPS 下无法登录或会话不稳定
确认 systemd 中已设置：
Environment=COOKIE_SECURE=1
10.5 端口 5000 被占用
修改 Gunicorn 绑定端口：
--bind 127.0.0.1:5001
同时修改 Nginx 的 proxy_pass：
proxy_pass http://127.0.0.1:5001;
11. 部署完成检查
curl http://127.0.0.1:5000/
sudo systemctl is-active spanish-diary
sudo nginx -t
浏览器访问：
http://your-domain.com
使用默认管理员登录后，应立即修改管理员密码。