9.2 KiB
Linux 单机手动部署参考
现行灰度环境使用 Jenkins 部署流程。本页保留独立主机的安装方法，不用于覆盖已有灰度服务。
适用场景：Ubuntu / Debian、已有域名、仅自己验收。使用系统 Python 3.10+，无需前端构建或 GPU。入口为 HTTPS → Nginx 全站访问密码 → 本机 Waitress → Flask / SQLite。
当前应用尚无完整登录会话、权限和会话数据隔离。验收期间必须保留全站访问密码，不能只保护 /admin，因为历史、导出和人工接口也能直接调用。此配置不代表已具备面向客户开放的权限体系。
1. 域名与网络
- 将验收子域名的 A 记录解析到服务器公网 IPv4；只有正确配置服务器 IPv6 后才添加 AAAA。
- 服务器安全组和防火墙允许 TCP 80、443，保留实际使用的 SSH 管理端口。不要开放应用端口 5000。
- 服务器需要能够出站访问 Python 包源及
https://api.deepseek.com。 - 下文的
chat.example.com均需替换成真实域名，包括 Nginx 配置内的证书路径。
2. 上传源码并安装依赖
首次部署使用 baiyue-logistics-chat-linux-acceptance.tar.gz。部署包包含本次工作区的部署文件和缺表修复，不含 .git、.env、虚拟环境、日志、数据库或本机附件。之前 Git 推送因认证失败未完成；若改用 Git 拉取，须先确认远端版本包含这些变更。
将部署包上传到服务器 /tmp/，以下命令均在服务器执行。首次部署假设 /opt/baiyue-logistics-chat 尚不存在；已有安装请使用文末更新流程。
sudo apt update
sudo apt install -y python3 python3-venv python3-pip nginx apache2-utils certbot
python3 --version
sudo tar --no-same-owner -xzf /tmp/baiyue-logistics-chat-linux-acceptance.tar.gz -C /opt
sudo adduser --system --group --home /nonexistent --no-create-home baiyue
sudo chown root:baiyue /opt/baiyue-logistics-chat
sudo chmod 750 /opt/baiyue-logistics-chat
cd /opt/baiyue-logistics-chat
sudo python3 -m venv .venv
sudo .venv/bin/python -m pip install -r requirements.txt
若系统已有专用 baiyue 用户，跳过 adduser。代码与虚拟环境归 root 所有；服务数据另存到 /var/lib/，无需让 Web 进程修改源码。
3. 配置 DS 密钥
仅首次复制配置，已有 .env 时跳过复制；不要把本机配置打进部署包。
sudo install -o root -g baiyue -m 640 .env.example .env
sudoedit /opt/baiyue-logistics-chat/.env
在编辑器内填写 DEEPSEEK_API_KEY=你的密钥，无需加 export，不要在终端命令或日志中输出密钥。文件由应用工厂读取；本方案的 systemd 单元不再注入同名环境变量。更换密钥后重启服务。
4. 启动应用服务
sudo install -m 644 deploy/baiyue-logistics-chat.service /etc/systemd/system/baiyue-logistics-chat.service
sudo systemd-analyze verify /etc/systemd/system/baiyue-logistics-chat.service
sudo systemctl daemon-reload
sudo systemctl enable --now baiyue-logistics-chat
sudo systemctl status baiyue-logistics-chat --no-pager
curl -I http://127.0.0.1:5000/
本机检查应返回 HTTP 200。服务使用独立系统用户、单进程 8 线程并仅监听 127.0.0.1:5000，不走 am.py 的 Flask 开发服务器回退。单进程保留当前应用的内存输入状态和限流行为；暂不配置多进程或多个副本。
systemd 自动创建并授权以下目录，重启与更新源码不会替换其中的数据：
| 内容 | 服务器路径 |
|---|---|
| SQLite | /var/lib/baiyue-logistics-chat/history.db |
| 上传附件 | /var/lib/baiyue-logistics-chat/uploads/ |
| 启动备份 | /var/lib/baiyue-logistics-chat/backups/ |
| 应用日志 | /var/log/baiyue-logistics-chat/app.log |
| 密钥配置 | /opt/baiyue-logistics-chat/.env |
首次启动创建八张业务表，不插入演示数据、默认客服账号或密码。已有表和记录保持兼容。应用当前仍会在启动时清理超过 7 天的上传文件，并执行启动备份；启动备份不能替代定时备份。
5. 申请 HTTPS 证书
先安装只提供证书验证路径的 HTTP 配置，此时不会转发到应用：
sudo install -d -m 755 /var/www/letsencrypt
sudo install -m 644 deploy/nginx-bootstrap.conf.example /etc/nginx/sites-available/baiyue-logistics-chat
sudoedit /etc/nginx/sites-available/baiyue-logistics-chat
sudo ln -s /etc/nginx/sites-available/baiyue-logistics-chat /etc/nginx/sites-enabled/baiyue-logistics-chat
sudo nginx -t
sudo systemctl enable --now nginx
sudo systemctl reload nginx
sudo certbot certonly --webroot -w /var/www/letsencrypt --cert-name chat.example.com -d chat.example.com
编辑配置时替换域名，申请证书时也替换两处域名；按 Certbot 提示填写邮箱和确认条款。若申请失败，先核对 DNS 和外网 80 端口，保留引导配置排查，暂不安装下一步需要证书的 TLS 配置。
6. 设置访问密码并开放 HTTPS 验收
创建验收账号 preview，密码由命令交互输入，不写入项目配置。-c 仅首次创建密码文件时使用；以后修改密码应去掉 -c。
sudo htpasswd -cB /etc/nginx/.baiyue-preview.htpasswd preview
sudo chown root:www-data /etc/nginx/.baiyue-preview.htpasswd
sudo chmod 640 /etc/nginx/.baiyue-preview.htpasswd
sudo install -m 644 deploy/nginx.conf.example /etc/nginx/sites-available/baiyue-logistics-chat
sudoedit /etc/nginx/sites-available/baiyue-logistics-chat
sudo nginx -t
sudo systemctl reload nginx
替换 TLS 配置中所有域名及证书路径；nginx -t 失败时先修正，不要继续 reload。模板的访问密码覆盖页面、附件、静态资源和全部 API，后端 5000 端口继续只对本机开放。不能只在导航层隐藏后台页面。
Nginx 已关闭代理响应缓冲及压缩，并将等待上游数据的超时设为 300 秒，供 AI SSE 分段输出；上传入口允许 12 MiB 请求体以容纳应用 10 MiB 文件上限外的表单开销。
7. 验收和证书续期
curl -I https://chat.example.com/
curl -I https://chat.example.com/api/export_chat
curl -u preview -I https://chat.example.com/
前两条应返回 401，证明页面和数据接口都受保护；第三条交互输入访问密码后应返回 200。浏览器也会先弹出访问密码：
- 客户页：
https://chat.example.com/，发送消息检查 DS 实际回复及流式显示。 - 验收工作台：
https://chat.example.com/admin/dashboard，从客户页申请人工，再检查接待和双向消息。 - 当前未预置应用内客服登录账号；Nginx 的
preview是整站验收密码，不是/admin页里的客服账号。
安装证书续期后的 Nginx 重载钩子，并检查续期定时器：
sudo install -d -m 755 /etc/letsencrypt/renewal-hooks/deploy
sudo install -m 755 deploy/reload-nginx.sh /etc/letsencrypt/renewal-hooks/deploy/baiyue-reload-nginx
sudo systemctl enable --now certbot.timer
sudo certbot renew --dry-run --run-deploy-hooks
最终配置保留 HTTP 的 /.well-known/acme-challenge/ 路径，供 webroot 续期使用；其他 HTTP 请求跳转到 HTTPS。不要删除验证路径或只对自己的 IP 开放证书验证端口，否则后续续期会失败。
维护、更新和问题定位
sudo journalctl -u baiyue-logistics-chat -n 100 --no-pager
sudo tail -n 100 /var/log/baiyue-logistics-chat/app.log
sudo systemctl restart baiyue-logistics-chat
sudo nginx -t
- 502：先查应用状态、journal 日志、依赖安装及 5000 端口本机检查。
- 一直弹访问密码：检查 Nginx 密码文件和
www-data读权限；不要用应用内客服密码替代验收密码。 - AI 无回复：确认服务器
.env已填写并重启，检查服务器能否访问 DS；本机验收成功不代表服务器网络已验证。 - 输出集中到最后：检查实际生效的 Nginx 配置和 CDN 是否重新启用了缓冲。
- 429：目前反向代理后的请求共享应用默认限流桶，适合单人验收；多人开放前需正确配置可信代理和业务限流。
更新前停止应用并备份 /var/lib/baiyue-logistics-chat/，另行保护 .env。源码更新只替换项目文件，不复制本机数据库或 work/，不覆盖服务器 .env；按需重新安装依赖后重启。若修改 systemd 单元，重新安装单元并执行 daemon-reload；若修改 Nginx，先检查再 reload。回退源码时仍保留数据副本，本项目尚无数据库降级迁移工具。
本地已通过应用工厂和全新数据库回归；目标服务器的 systemd-analyze verify、nginx -t、DNS、证书签发及真实 DS 请求仍需在部署时验证。
参考
工厂调用与监听参数依据 Waitress 官方文档。流式转发配置依据 Nginx 代理模块，全站密码依据 Nginx Basic Auth 模块。证书和续期使用 Certbot webroot；服务目录与只读保护依据 systemd.exec。