zhiyin/docs/DEPLOYMENT.md

# 职引 - 部署文档

## 目录
1. [环境要求](#环境要求)
2. [后端部署](#后端部署)
3. [前端部署（H5）](#前端部署h5)
4. [微信小程序部署](#微信小程序部署)
5. [数据库初始化](#数据库初始化)
6. [监控和日志](#监控和日志)

---

## 环境要求

### 生产服务器
- **操作系统**: Linux (Ubuntu 20.04+ / CentOS 7+)
- **Node.js**: 18.x 或更高版本
- **MongoDB**: 4.4+ (或 MongoDB Atlas 云服务)
- **Nginx**: 1.18+ (反向代理)
- **PM2**: 进程管理

### 本地开发
- **Node.js**: 18.x
- **MongoDB**: 本地或云服务
- **HBuilderX**: uni-app 开发

---

## 后端部署

### 1. 安装依赖
```bash
cd backend
npm install --production
```

### 2. 配置环境变量
复制 `.env.example` 为 `.env.production` 并修改：
```bash
cp .env.example .env.production
vim .env.production  # 修改生产配置
```

**关键配置项**：
- `MONGODB_URI`: 生产数据库地址
- `JWT_SECRET`: 强密钥（至少32字符）
- `PORT`: 生产端口（推荐 3000）
- `WECHAT_APPID` / `WECHAT_SECRET`: 小程序生产凭证

### 3. 编译 TypeScript
```bash
npm run build
```

### 4. 使用 PM2 启动
```bash
# 安装 PM2
npm install -g pm2

# 启动应用
pm2 start dist/main.js --name zhiyin-backend

# 设置开机自启
pm2 startup
pm2 save
```

### 5. 配置 Nginx 反向代理
```nginx
server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
```

---

## 前端部署（H5）

### 1. 修改 API 地址
编辑 `zhiyin-app/config/api.js`：
```javascript
export const BASE_URL = 'https://api.yourdomain.com/api'
```

### 2. 编译 H5
```bash
cd zhiyin-app
npm run build:h5
```

### 3. 部署到 Web 服务器
将 `dist/build/h5/` 目录上传到服务器：
```bash
# 使用 scp 上传
scp -r dist/build/h5/* user@your-server:/var/www/zhiyin/

# 或使用 FTP/SSH 上传
```

### 4. 配置 Nginx
```nginx
server {
    listen 80;
    server_name yourdomain.com;

    root /var/www/zhiyin;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

---

## 微信小程序部署

### 1. 修改配置
编辑 `zhiyin-app/manifest.json`：
```json
{
  "mp-weixin": {
    "appid": "your-production-appid"
  }
}
```

### 2. 编译小程序
```bash
cd zhiyin-app
npm run build:mp-weixin
```

### 3. 使用微信开发者工具上传
1. 打开微信开发者工具
2. 导入 `dist/build/mp-weixin/` 目录
3. 点击「上传」按钮
4. 填写版本号和项目备注
5. 登录微信公众平台提交审核

### 4. 提交审核前检查
- ✅ 已配置合法域名（在微信公众平台）
- ✅ 已通过 AI 深度合成类目审批
- ✅ 已配置隐私协议和用户协议
- ✅ 已测试所有核心功能

---

## 数据库初始化

### 1. 创建数据库和用户
```bash
mongo
> use zhiyin
> db.createUser({
    user: "zhiyin",
    pwd: "strong-password",
    roles: [{ role: "readWrite", db: "zhiyin" }]
  })
```

### 2. 创建索引
```bash
cd backend
node scripts/create-indexes.js
```

### 3. 初始化管理员账号（可选）
```bash
node scripts/create-admin.js
```

---

## 监控和日志

### 1. 日志配置
使用 PM2 查看日志：
```bash
pm2 logs zhiyin-backend
pm2 logs zhiyin-backend --lines 100
```

### 2. 错误监控
推荐集成：
- **Sentry**: 错误追踪
- **PM2 Plus**: 进程监控
- **MongoDB Atlas**: 数据库监控

### 3. 性能监控
```bash
# 查看进程状态
pm2 monit

# 查看资源占用
pm2 list
```

---

## 常见问题

### Q1: MongoDB 连接失败
**A**: 检查 `.env.production` 中的 `MONGODB_URI` 是否正确，确保数据库可访问。

### Q2: 微信小程序请求失败
**A**: 确保在微信公众平台配置了合法域名（必须是 HTTPS）。

### Q3: AI 调用失败
**A**: 检查 `AI_PRIMARY_KEY` 和 `AI_BACKUP_KEY` 是否正确，确保 API 额度充足。

---

## 安全检查清单

- [ ] 已修改默认 JWT_SECRET
- [ ] 已禁用开发模式的固定验证码
- [ ] 已配置 CORS 白名单
- [ ] 已启用 HTTPS
- [ ] 已配置 MongoDB 访问权限
- [ ] 已移除控制台日志（生产环境）
- [ ] 已配置速率限制（防止滥用）

---

## 回滚方案

如果需要回滚到上一个版本：
```bash
# 1. 查看 PM2 历史
pm2 logs zhiyin-backend --lines 1000

# 2. 重启到上一个版本
pm2 restart zhiyin-backend --version <previous-version>

# 3. 数据库回滚（如有迁移）
mongorestore --uri="<connection-string>" --drop backup/
```

---

**最后更新**: 2026-06-02