# 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（可选）