alboped
132f51705e
完善会话消息删除、Qwen 联网搜索/深度思考参数与 SSE 来源事件，同时增加请求体日志与 TS6 配置兼容调整，并新增 Ubuntu+PM2+Nginx 的部署文档与脚本以支持可回滚发布。 Made-with: Cursor
250 lines
5.3 KiB
Markdown
250 lines
5.3 KiB
Markdown
# 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. 目录约定
|
||
|
||
```bash
|
||
/srv/chat-one-service/
|
||
releases/
|
||
20260423_120000/
|
||
current -> /srv/chat-one-service/releases/20260423_120000
|
||
shared/
|
||
.env
|
||
logs/
|
||
```
|
||
|
||
初始化目录：
|
||
|
||
```bash
|
||
sudo mkdir -p /srv/chat-one-service/{releases,shared/logs}
|
||
sudo chown -R chatone:chatone /srv/chat-one-service
|
||
```
|
||
|
||
## 4. 运行时安装
|
||
|
||
```bash
|
||
# 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` 写入：
|
||
|
||
```dotenv
|
||
# 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` 用户执行：
|
||
|
||
```bash
|
||
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"
|
||
```
|
||
|
||
启动：
|
||
|
||
```bash
|
||
cd /srv/chat-one-service/current
|
||
pm2 start ecosystem.config.js --env production
|
||
pm2 save
|
||
pm2 startup
|
||
```
|
||
|
||
## 7. 日常发布流程（零停机）
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
发布后验证：
|
||
|
||
```bash
|
||
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`
|
||
|
||
生效步骤：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
sudo certbot --nginx -d api.example.com
|
||
```
|
||
|
||
## 9. 回滚策略
|
||
|
||
### 9.1 代码回滚（快速）
|
||
|
||
```bash
|
||
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）：
|
||
|
||
```bash
|
||
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. 常用排障命令
|
||
|
||
```bash
|
||
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（可选）
|