# 部署指南

> 2026-06-14 更新:已废弃 Webhook 自动部署方案,改为**手动 SSH 部署**。

## 服务器信息

- 主机: `8.159.134.106` (SSH 别名: `aliyunos4`)
- SSH 端口: `22622`
- 用户: `root`
- 部署目录: `/data/ai/audio_codebuddy`
- 前端产物目录: `/data/ai/frontend/build/h5` (线上 nginx root 指向)
- 后端端口: `3100` (PM2 进程名 `server`)

## 手动部署流程

```bash
# 1. SSH 到服务器
ssh aliyunos4

# 2. 进入项目目录
cd /data/ai/audio_codebuddy

# 3. 拉取最新代码 (git pull,或本地 scp 上传后 git checkout)
# 方式 A: git pull (gogs 正常时)
git pull origin master

# 方式 B: 本地 scp 推送 (gogs 500 故障时)
#    在本地执行:
#    scp -P 22622 -r <本地路径> aliyunos4:/data/ai/audio_codebuddy/<目标路径>

# 4. 构建后端
cd server
npx prisma generate    # 如果改动了 prisma/schema.prisma
npm install             # 如果改动了 package.json
npm run build

# 5. 构建前端
cd ../my-uniapp-vue3
npm install
npm run build:h5
rm -rf /data/ai/audio/frontend/build/h5
cp -r dist/build/h5 /data/ai/audio/frontend/build/h5

# 6. 重启后端
pm2 delete server 2>/dev/null || true
SERVER_PORT=3100 pm2 start dist/app.js --name server
pm2 save
```

## ⛔ 发布上线前必跑：核心业务测试

> 业务核心链路 = **书籍 大纲 → 内容 → 音频** 端到端链路。
> 任何 `book-generator / langgraph / TTS / 前端 book-generator 页面` 改动，**发布前必须**跑通这条链路，否则视为不可发布。

```bash
# 在仓库根目录，自动起服务 + 跑测试
./scripts/run-core-business-test.sh

# 服务已起好的话
SKIP_SERVER=1 ./scripts/run-core-business-test.sh

# 报告位置
tests/test-results/report/index.html      # 失败时打开
tests/test-results/results.json            # 结构化结果
```

参考时长 **3 ~ 8 分钟**（真实 LLM + TTS 调用）。失败立即停手，定位修复后重跑。

完整规范、失败处理、新人入职清单详见 **[CONTRIBUTING.md](./CONTRIBUTING.md)**。

## 🪝 安装 git hooks（推荐每位开发者本地安装）

```bash
./scripts/install-hooks.sh
```

装好后：
- `git commit` 检测到核心业务文件改动 → 自动跑核心业务测试
- `git push` → 强制跑一次核心业务测试

绕过：`git commit --no-verify` / `git push --no-verify`（必须在 PR 描述里说明）

卸载：`./scripts/install-hooks.sh --uninstall`

## 故障排查

```bash
# 查看后端 PM2 状态
pm2 list
pm2 logs server --lines 100

# 查看健康检查
curl -s http://localhost:3100/health

# 查看 nginx 配置
cat /etc/nginx/conf.d/*.conf

# 清理服务器磁盘(临时文件)
ssh aliyunos4 'du -sh /data/ai/audio_codebuddy/server/temp/* 2>/dev/null'
```