155 lines
9.2 KiB
Markdown
155 lines
9.2 KiB
Markdown
# Linux 单机手动部署参考
|
|
|
|
现行灰度环境使用 [Jenkins 部署流程](deployment.md)。本页保留独立主机的安装方法，不用于覆盖已有灰度服务。
|
|
|
|
适用场景：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` 尚不存在；已有安装请使用文末更新流程。
|
|
|
|
```bash
|
|
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` 时跳过复制；不要把本机配置打进部署包。
|
|
|
|
```bash
|
|
sudo install -o root -g baiyue -m 640 .env.example .env
|
|
sudoedit /opt/baiyue-logistics-chat/.env
|
|
```
|
|
|
|
在编辑器内填写 `DEEPSEEK_API_KEY=你的密钥`，无需加 `export`，不要在终端命令或日志中输出密钥。文件由应用工厂读取；本方案的 systemd 单元不再注入同名环境变量。更换密钥后重启服务。
|
|
|
|
## 4. 启动应用服务
|
|
|
|
```bash
|
|
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 配置，此时不会转发到应用：
|
|
|
|
```bash
|
|
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`。
|
|
|
|
```bash
|
|
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. 验收和证书续期
|
|
|
|
```bash
|
|
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 重载钩子，并检查续期定时器：
|
|
|
|
```bash
|
|
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 开放证书验证端口，否则后续续期会失败。
|
|
|
|
## 维护、更新和问题定位
|
|
|
|
```bash
|
|
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 官方文档](https://docs.pylonsproject.org/projects/waitress/en/stable/runner.html)。流式转发配置依据 [Nginx 代理模块](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering)，全站密码依据 [Nginx Basic Auth 模块](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html)。证书和续期使用 [Certbot webroot](https://eff-certbot.readthedocs.io/en/stable/using.html#webroot)；服务目录与只读保护依据 [systemd.exec](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html)。
|