Files

alboped 132f51705e feat: 增强 Chat 能力并补充单机部署方案

完善会话消息删除、Qwen 联网搜索/深度思考参数与 SSE 来源事件，同时增加请求体日志与 TS6 配置兼容调整，并新增 Ubuntu+PM2+Nginx 的部署文档与脚本以支持可回滚发布。

Made-with: Cursor

2026-04-23 22:31:18 +08:00

5.3 KiB

Raw Blame History

ChatOne Service 单机部署指南（Ubuntu + PM2 + Nginx）

本文给出 chat-one-service 在单机 Linux 环境的可执行部署流程，覆盖：

服务器基线检查
生产环境变量合同
发布与回滚流程
Nginx 反向代理（含 SSE）
监控、备份与巡检

1. 适用范围

OS：Ubuntu 22.04 LTS
Runtime：Node.js 22.x
进程管理：PM2
反向代理：Nginx
依赖：PostgreSQL、Redis（可为外部托管）

2. 服务器基线检查（部署前）

2.1 主机与网络

已准备公网域名（示例：api.example.com）
22/80/443 已开放
应用端口（默认 3000）仅允许本机访问
时区与 NTP 已校准（timedatectl status）

2.2 账号与权限

创建专用用户：chatone
禁止 root 直登，仅 SSH Key 登录
chatone 拥有 /srv/chat-one-service 读写权限

2.3 依赖连通性

PostgreSQL 可连接（DATABASE_URL 可用）
Redis 可连接（REDIS_HOST/PORT 可用）
第三方 AI API Key 已可用（如 QWEN_API_KEY）

3. 目录约定

/srv/chat-one-service/
  releases/
    20260423_120000/
  current -> /srv/chat-one-service/releases/20260423_120000
  shared/
    .env
    logs/

初始化目录：

sudo mkdir -p /srv/chat-one-service/{releases,shared/logs}
sudo chown -R chatone:chatone /srv/chat-one-service

4. 运行时安装

# Node.js 22（nvm 方式，推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.nvm/nvm.sh
nvm install 22
nvm use 22

# Yarn + PM2
npm i -g yarn pm2

# Nginx + certbot
sudo apt-get update
sudo apt-get install -y nginx certbot python3-certbot-nginx postgresql-client redis-tools

5. 生产环境变量合同（shared/.env）

在 /srv/chat-one-service/shared/.env 写入：

# app
NODE_ENV=production
PORT=3000
APP_NAME=chat-one-service

# jwt（至少 32 位随机串）
JWT_ACCESS_SECRET=replace-with-long-random-string
JWT_REFRESH_SECRET=replace-with-long-random-string
JWT_ACCESS_EXPIRES_IN=2h
JWT_REFRESH_EXPIRES_IN=30d

# database
DATABASE_URL=postgresql://user:password@host:5432/chat_one?schema=public

# redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_KEY_PREFIX_CLIENT=chatone:client
REDIS_KEY_PREFIX_ADMIN=chatone:admin

# ai
QWEN_API_KEY=
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
DEEPSEEK_API_KEY=
VOLC_API_KEY=

# ai route
AI_ROUTE_RETRY_TIMES=1
AI_ROUTE_TIMEOUT_MS=45000

安全要求：

.env 仅服务器本地保存，不入仓库。
定期轮换密钥，变更后执行 pm2 reload chat-one-service --update-env。

6. 首次部署流程

以下命令以 chatone 用户执行：

set -e
APP_ROOT=/srv/chat-one-service
RELEASE="$APP_ROOT/releases/$(date +%Y%m%d_%H%M%S)"

mkdir -p "$RELEASE"
git clone <your-repo-url> "$RELEASE"
cd "$RELEASE"

yarn install --frozen-lockfile
yarn build
npx prisma migrate deploy

ln -sfn "$RELEASE" "$APP_ROOT/current"

启动：

cd /srv/chat-one-service/current
pm2 start ecosystem.config.js --env production
pm2 save
pm2 startup

7. 日常发布流程（零停机）

set -e
APP_ROOT=/srv/chat-one-service
RELEASE="$APP_ROOT/releases/$(date +%Y%m%d_%H%M%S)"

mkdir -p "$RELEASE"
git clone <your-repo-url> "$RELEASE"
cd "$RELEASE"

yarn install --frozen-lockfile
yarn build
npx prisma migrate deploy

ln -sfn "$RELEASE" "$APP_ROOT/current"
pm2 reload chat-one-service --update-env

发布后验证：

curl -fsS http://127.0.0.1:3000/api/docs >/dev/null
curl -fsS https://api.example.com/api/docs >/dev/null

如需 SSE 冒烟测试，调用：

POST /api/client/v1/chat/completions/stream

8. Nginx 配置（含 SSE）

参考文件：deploy/nginx/chat-one-service.conf

生效步骤：

sudo cp deploy/nginx/chat-one-service.conf /etc/nginx/sites-available/chat-one-service.conf
sudo ln -sfn /etc/nginx/sites-available/chat-one-service.conf /etc/nginx/sites-enabled/chat-one-service.conf
sudo nginx -t
sudo systemctl reload nginx

申请 HTTPS：

sudo certbot --nginx -d api.example.com

9. 回滚策略

9.1 代码回滚（快速）

APP_ROOT=/srv/chat-one-service
ls -1dt "$APP_ROOT"/releases/* | sed -n '1,2p'  # 找到上一个版本
ln -sfn <previous-release-path> "$APP_ROOT/current"
pm2 reload chat-one-service --update-env

9.2 数据回滚（高风险）

仅在迁移引发严重问题时执行。
使用最近一次全量备份恢复（建议维护停机窗口）。

10. 备份与监控最小集

10.1 PostgreSQL 备份

每日定时（cron）：

pg_dump "$DATABASE_URL" | gzip > /data/backup/chat_one_$(date +%F).sql.gz

建议：

保留 7-14 天
同步到对象存储（异地）

10.2 应用观测

PM2：重启次数、内存、CPU
Nginx：4xx/5xx 比率、延迟
Redis：连接数与内存
日志：按天滚动，至少保留 7 天

11. 常用排障命令

pm2 ls
pm2 logs chat-one-service --lines 200
pm2 describe chat-one-service

sudo systemctl status nginx
sudo tail -n 200 /var/log/nginx/error.log

curl -i http://127.0.0.1:3000/api/docs

12. 安全加固建议

安全组白名单限制 SSH 来源
开启 UFW，仅放行 22/80/443
禁止将 .env、备份明文文件提交到 Git
配置 fail2ban（可选）

5.3 KiB Raw Blame History Unescape Escape