# 生产运行手册

## 服务器准备

- 安装 Docker、Docker Compose plugin、Git。
- 域名 `bigdata.dtacloud.cn` 解析到服务器公网 IP。
- 服务器公网 80/443 由外层 nginx 负责；本项目 Caddy 只监听 `127.0.0.1:8082`，不直接暴露公网。
- 项目目录建议：`/srv/dlbdi`。
- 证书与密钥放入 `/srv/dlbdi/secrets/wechatpay/`，不要提交 Git。

## 首次部署

```bash
git clone <repo-url> /srv/dlbdi
cd /srv/dlbdi
cp .env.production.example .env.production
mkdir -p secrets/wechatpay backups
printf '%s\n' '<replace-with-alertmanager-token>' > secrets/alertmanager_token
```

编辑 `.env.production`：

- 设置强随机 `POSTGRES_PASSWORD`、`MINIO_ROOT_PASSWORD`、`JWT_SECRET`。
- 设置 `ALERTMANAGER_TOKEN`，并让 `secrets/alertmanager_token` 的内容与它一致。
- 设置 `GRAFANA_ADMIN_PASSWORD`，不要使用样例密码。
- 如使用 Sentry，配置 `SENTRY_DSN` 和 `NEXT_PUBLIC_SENTRY_DSN`。
- 配置阿里云短信变量。
- 配置小程序 AppID/Secret。
- 配置微信支付商户号、AppID、V3 key、证书序列号、公钥 ID、证书路径。
- 保持 `ENABLE_DEV_AUTH_CODE=false`、`ENABLE_DEV_PAYMENT=false`、`ENABLE_DEV_ADMIN_TOKEN=false`。

启动：

```bash
make audit-production
make backup
make deploy
make migrate
```

## 服务路由

- Web：`https://bigdata.dtacloud.cn`
- Backend：`https://bigdata.dtacloud.cn/api`
- 健康检查：`https://bigdata.dtacloud.cn/api/health`
- 深度健康检查：`https://bigdata.dtacloud.cn/api/health/deep`
- Prometheus 指标：公网不开放；Prometheus 容器从内网 `http://backend:4000/api/metrics` 抓取
- 公共文件代理：`https://bigdata.dtacloud.cn/files/<bucket>/<objectKey>`
- Grafana：服务器本机 `127.0.0.1:3001`
- Prometheus：服务器本机 `127.0.0.1:9090`
- Alertmanager：服务器本机 `127.0.0.1:9093`

## 微信后台配置

- 小程序 request 合法域名：`https://bigdata.dtacloud.cn`
- 微信支付 JSAPI 支付授权目录：`https://bigdata.dtacloud.cn/`
- Native 支付回调：`https://bigdata.dtacloud.cn/api/payments/wechat/notify`
- 商户平台 APIv3 key、公钥、商户 API 证书要与服务器 `.env.production` 对齐。

## 常用操作

```bash
make logs
make backup
npm --prefix backend run files:migrate:s3
docker compose --env-file .env.production ps
docker compose --env-file .env.production restart backend
docker compose --env-file .env.production restart web
```

## 对象存储迁移

首次切换 MinIO 后先检查：

```bash
curl https://bigdata.dtacloud.cn/api/health/deep
```

确认 `objectStorage.status=ok` 后迁移旧文件：

```bash
cd /srv/dlbdi/backend
FILE_MIGRATION_LIMIT=100 npm run files:migrate:s3
```

迁移脚本只更新 `uploaded_files` 的 S3 元数据，不删除旧本地文件或数据库原内容。确认发票、商品图、交付文件、专家材料全部可访问后，再单独做旧文件归档。

## 异常处理中心

- 后台入口：`/admin/exceptions`
- 可处理支付、短信、文件、发票、监控告警等 `operational_events`。
- Alertmanager 通过 `/api/internal/alerts/prometheus` 写入事件。
- 处理动作会记录员工审计日志。

## 发布流程

1. 本地或 CI 通过所有检查。
2. 合并到 `main` 或 `release-v1`。
3. 服务器执行 `git pull --ff-only`。
4. 执行 `make audit-production`。
5. 执行 `make backup`。
6. 执行 `make deploy`。
7. 执行 `make migrate`。
8. 检查 `/api/health/deep`。
9. 完成登录、下单、支付、小程序真机冒烟。

## 回滚流程

1. 保留当前错误日志和容器日志。
2. 找到上一个可用 Git commit。
3. `git checkout <commit>`。
4. `make deploy`。
5. 若数据库迁移不可逆，不直接回滚数据库，按 `docs/BACKUP_RESTORE.md` 在临时环境验证恢复方案后再操作。
