DIP1 生产环境管理员操作手册¶

文档编号：DOC-D01-OPS
版本：V1.0
创建日期：2026-08-11
最后更新：2026-08-11
维护人：TL / DT
适用范围：DIP1 生产环境运维管理

一、系统架构概述¶

1.1 服务架构图¶

┌─────────────────────────────────────────────────────────────────┐
│  Docker Compose (dip1-prod-network)                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  dip1-api-1 (FastAPI 应用服务)                           │   │
│  │  ├── 端口: 8000                                        │   │
│  │  ├── 镜像: weavely/dip1-api:v2.0.0-prod                │   │
│  │  ├── 健康检查: /health (API + DB 双重检查)             │   │
│  │  ├── 日志级别: WARNING                                  │   │
│  │  └── 非 root 用户运行                                   │   │
│  └─────────────────────────────────────────────────────────┘   │
│                          │                                      │
│                          ▼                                      │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  dip1-prod-postgres (PostgreSQL 16)                     │   │
│  │  ├── 端口: 5432                                        │   │
│  │  ├── 数据库: dip1_prod                                 │   │
│  │  ├── 用户名: dip1_prod                                │   │
│  │  ├── 表数量: 34 张                                     │   │
│  │  └── 持久化卷: dip1-postgres-data                      │   │
│  └─────────────────────────────────────────────────────────┘   │
│                          │                                      │
│                          ▼                                      │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  dip1-prod-redis (Redis 7)                              │   │
│  │  ├── 端口: 6379                                        │   │
│  │  ├── 用途: 缓存 + 会话 + 队列                           │   │
│  │  └── 持久化卷: dip1-redis-data                         │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

1.2 端口分配¶

服务	端口	说明
API	8000	FastAPI 应用服务
PostgreSQL	5432	主数据库
Redis	6379	缓存服务

1.3 目录结构¶

dip1/
├── backend/                    # 后端代码
│   ├── app/                    # 应用代码
│   │   ├── interfaces/api/    # API 层
│   │   ├── application/       # 应用服务层
│   │   ├── domain/            # 领域模型
│   │   └── infrastructure/    # 基础设施
│   ├── alembic/                # 数据库迁移
│   └── tests/                  # 测试
├── frontend/                   # 前端代码
│   ├── apps/
│   │   ├── opr-admin/        # 运营后台
│   │   ├── wkr-app/          # 师傅端 App
│   │   └── cst-app/          # 客户端 App
│   └── packages/              # 共享包
├── docker-compose.prod.yml     # 生产环境编排
├── .env.prod.local             # 生产环境变量（本地测试）
└── Dockerfile                  # API 镜像构建

二、快速开始¶

2.1 前置条件¶

Docker >= 24.x
Docker Compose >= 2.x
操作系统：Linux (Ubuntu 20.04+) / Windows Server 2019+
内存：>= 4GB（PostgreSQL + Redis + API）
磁盘：>= 50GB（数据库 + 日志 + 镜像）

2.2 首次部署¶

# 1. 克隆代码
git clone <repository-url>/dip1.git
cd dip1

# 2. 创建生产环境变量文件
cp .env.prod.local .env.prod
# 编辑 .env.prod 填入真实生产配置

# 3. 构建并启动所有服务
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --build

# 4. 执行数据库迁移
docker exec dip1-api-1 alembic upgrade head

# 5. 导入种子数据
docker exec dip1-api-1 python -m app.infrastructure.db.seed.cli

# 6. 验证部署
curl http://localhost:8000/health
# 预期返回: {"status":"ok","env":"prod","db":"ok"}

2.3 日常运维命令¶

# 查看所有服务状态
docker compose -f docker-compose.prod.yml ps

# 查看 API 日志（最近 100 行）
docker logs dip1-api-1 --tail 100

# 查看实时日志
docker logs -f dip1-api-1

# 重启 API 服务
docker compose -f docker-compose.prod.yml restart api

# 重启所有服务
docker compose -f docker-compose.prod.yml restart

# 停止所有服务
docker compose -f docker-compose.prod.yml down

# 停止并删除数据卷（⚠️ 慎用，会删除数据库）
docker compose -f docker-compose.prod.yml down -v

三、环境变量配置¶

3.1 环境变量清单¶

文件位置：dip1/.env.prod

# ====== 基础配置 ======
ENV=prod                              # 固定为 prod
TZ=Asia/Hong_Kong                     # 时区
APP_VERSION=2.0.0                     # 版本号

# ====== 安全密钥 ======
# ⚠️ 必须使用 32 字节随机密钥，定期轮换
# 生成命令: python -c "import secrets,base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
APP_SECRET_KEY=<32字节随机密钥>

# ====== CORS 配置 ======
# 生产环境只允许以下域名访问
CORS_ORIGINS=["https://admin.weavely.hk","https://wkr.weavely.hk","https://cst.weavely.hk"]

# ====== PostgreSQL ======
DATABASE_URL=postgresql+asyncpg://dip1_prod:<数据库密码>@postgres:5432/dip1_prod
DB_POOL_SIZE=20                       # 连接池初始大小
DB_MAX_OVERFLOW=40                    # 最大溢出连接
DB_PASSWORD=<数据库密码>              # 与 DATABASE_URL 中密码一致

# ====== Redis ======
REDIS_URL=redis://redis:6379/0

# ====== Cloudflare R2（对象存储）======
R2_ACCOUNT_ID=<R2账户ID>
R2_ACCESS_KEY_ID=<R2访问密钥ID>
R2_SECRET_ACCESS_KEY=<R2访问密钥>
R2_BUCKET=dip1-assets-prod
R2_PUBLIC_URL=https://assets.weavely.hk

# ====== JWT 配置 ======
JWT_ALGORITHM=HS256                   # 算法
JWT_ACCESS_TOKEN_TTL_MIN=15           # Access Token 有效期（分钟）
JWT_REFRESH_TOKEN_TTL_DAY=30          # Refresh Token 有效期（天）
JWT_ACCESS_TTL_SECONDS=900             # Access Token 有效期（秒）
JWT_REFRESH_TTL_SECONDS=2592000       # Refresh Token 有效期（秒）

# ====== OTP 配置 ======
OTP_TTL_SECONDS=300                   # OTP 有效期（秒）
OTP_RATE_LIMIT_PER_HOUR=5             # 每小时发送限制
BIOMETRIC_REQUIRED=false              # 是否强制生物识别

# ====== Expo / EAS ======
EXPO_USERNAME=weavely-dip1
EXPO_PROJECT_ID_WKR=<师傅端项目ID>
EXPO_PROJECT_ID_CST=<客户端项目ID>
EAS_PROJECT_ACCOUNT=weavely-dip1
EXPO_PUSH_AUTH_TOKEN=<Expo推送Token>

# ====== 可观测性 ======
SENTRY_DSN=<Sentry DSN>               # Sentry 错误追踪
LARK_WEBHOOK_ALERT=<飞书Webhook>      # 告警通知
OTEL_EXPORTER_OTLP_ENDPOINT=<OTLP端点> # OpenTelemetry

# ====== 日志配置 ======
LOG_LEVEL=WARNING                     # DEBUG / INFO / WARNING / ERROR

3.2 密钥管理规范¶

JWT 密钥
长度：32 字节
存储：环境变量，禁止提交到 Git
轮换：每 90 天轮换一次
生成：python -c "import secrets,base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
数据库密码
长度：>= 16 字符
组成：大小写字母 + 数字 + 特殊字符
存储：环境变量
轮换：每 180 天轮换一次
R2 存储密钥
来源：Cloudflare Dashboard
权限：最小权限原则（仅读写 dip1-assets-prod bucket）
轮换：每 90 天轮换一次

四、数据库管理¶

4.1 数据库连接¶

# 连接 PostgreSQL
docker exec -it dip1-prod-postgres psql -U dip1_prod -d dip1_prod

# 或从 API 容器连接
docker exec -it dip1-api-1 python -c "
import asyncio
from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine('postgresql+asyncpg://dip1_prod:dip1_prod_pass_2026@postgres:5432/dip1_prod')
print('数据库连接成功')
"

4.2 常用 SQL 查询¶

-- 查看用户数量
SELECT count(*) as user_count FROM sys_users;

-- 查看角色权限
SELECT r.role_id, r.role_name, count(rp.permission_key) as perm_count
FROM sys_roles r
LEFT JOIN sys_role_permissions rp ON r.role_id = rp.role_id
GROUP BY r.role_id, r.role_name;

-- 查看师傅信息
SELECT worker_id, display_name, rating, jobs_completed
FROM mds_wpl_workers
WHERE status = 'active';

-- 查看最近订单
SELECT order_id, customer_name, status, created_at
FROM cpt_orders
ORDER BY created_at DESC
LIMIT 20;

-- 查看系统参数版本
SELECT version_id, version, is_active, updated_at
FROM qsv_param_versions
ORDER BY updated_at DESC;

4.3 数据库迁移¶

# 查看当前迁移版本
docker exec dip1-api-1 alembic current

# 查看迁移历史
docker exec dip1-api-1 alembic history

# 升级到最新版本
docker exec dip1-api-1 alembic upgrade head

# 回滚一个版本（⚠️ 谨慎使用）
docker exec dip1-api-1 alembic downgrade -1

# 回滚到初始状态（⚠️ 危险，会删除所有表）
docker exec dip1-api-1 alembic downgrade base

4.4 种子数据¶

# 插入基础种子数据（角色、权限、管理员、品类）
docker exec dip1-api-1 python -m app.infrastructure.db.seed.cli

# ⚠️ 注意：种子数据幂等，可重复执行不会产生重复数据

4.5 数据备份与恢复¶

备份：

# 全量备份
docker exec dip1-prod-postgres pg_dump -U dip1_prod dip1_prod > backup_$(date +%Y%m%d_%H%M%S).sql

# 仅结构备份
docker exec dip1-prod-postgres pg_dump -U dip1_prod --schema-only dip1_prod > schema_backup.sql

# 仅数据备份
docker exec dip1-prod-postgres pg_dump -U dip1_prod --data-only dip1_prod > data_backup.sql

恢复：

# 恢复全量备份
cat backup_20260811_150000.sql | docker exec -i dip1-prod-postgres psql -U dip1_prod -d dip1_prod

# ⚠️ 恢复前请备份当前数据

定时备份（crontab 示例）：

# 每天凌晨 3 点自动备份
0 3 * * * cd /path/to/dip1 && docker compose -f docker-compose.prod.yml exec -T postgres pg_dump -U dip1_prod dip1_prod > /backup/dip1_$(date +\%Y\%m\%d).sql

五、日志管理¶

5.1 查看日志¶

# API 服务日志
docker logs dip1-api-1 --tail 200          # 最近 200 行
docker logs -f dip1-api-1                  # 实时追踪
docker logs --since 1h dip1-api-1          # 最近 1 小时
docker logs --since "2026-08-11T10:00:00" dip1-api-1

# PostgreSQL 日志
docker logs dip1-prod-postgres --tail 100

# Redis 日志
docker logs dip1-prod-redis --tail 100

5.2 日志级别¶

生产环境默认 LOG_LEVEL=WARNING，可选值：

级别	说明	生产环境建议
DEBUG	详细调试信息	❌ 禁用
INFO	常规运行信息	❌ 禁用
WARNING	警告信息	✅ 默认
ERROR	错误信息	✅ 始终启用

临时调整日志级别（无需重建镜像）：

# 进入容器
docker exec -it dip1-api-1 bash

# 临时修改配置
# 方法1: 修改环境变量后重启
# 方法2: 直接修改代码中的日志配置

5.3 日志持久化¶

生产环境建议配置日志持久化，可使用以下方案之一：

文件日志（推荐）
修改 docker-compose.prod.yml 添加日志驱动配置
使用 json-file 驱动，自动轮转
集中日志（可选）
接入 ELK Stack / Loki / Datadog
通过 OpenTelemetry 导出

Docker 日志配置示例：

# 在 docker-compose.prod.yml 中添加
services:
  api:
    logging:
      driver: json-file
      options:
        max-size: "100m"
        max-file: "5"

六、健康检查与监控¶

6.1 健康检查端点¶

GET /health

响应示例：

{
    "status": "ok",           // ok / error
    "service": "weavely-dip1-api",
    "version": "2.0.0",
    "env": "prod",           // prod / staging / dev
    "db": "ok"               // ok / error（数据库连接状态）
}

各字段含义：

字段	说明	异常处理
status	服务状态	error → 立即检查
db	数据库状态	error → 检查数据库连接

6.2 监控建议¶

监控项	阈值	告警级别
API 响应时间	> 500ms	WARNING
数据库连接数	> 80% 最大连接	WARNING
API 错误率	> 1%	ERROR
内存使用	> 80%	WARNING
磁盘使用	> 85%	WARNING
CPU 使用	> 80%	WARNING

6.3 告警通知¶

生产环境可配置以下告警通道：

飞书 Webhook（LARK_WEBHOOK_ALERT）
Sentry（错误追踪 + 邮件通知）
邮件通知（可选）

七、故障排查¶

7.1 常见问题诊断¶

问题	诊断命令	可能原因	解决方案
API 无法访问	`curl http://localhost:8000/health`	容器未启动	`docker compose up -d`
数据库连接失败	`docker logs dip1-api-1`	密码/网络错误	检查 `DATABASE_URL`
Redis 连接失败	`docker logs dip1-api-1`	服务未启动	`docker compose start redis`
认证失败	`docker logs dip1-api-1`	JWT 密钥问题	检查 `APP_SECRET_KEY`
端口冲突	`docker ps`	端口被占用	停止旧容器或修改端口

7.2 故障恢复流程¶

1. 发现异常
   └── 通过监控告警 / 用户反馈

2. 诊断问题
   ├── 查看健康检查: curl http://localhost:8000/health
   ├── 查看容器状态: docker compose -f docker-compose.prod.yml ps
   └── 查看日志: docker logs dip1-api-1 --tail 100

3. 执行恢复
   ├── 临时恢复: docker compose -f docker-compose.prod.yml restart
   ├── 根本修复: 修改配置 / 代码后重新部署
   └── 数据恢复: 从备份恢复数据库

4. 验证恢复
   ├── 健康检查通过
   ├── 核心接口测试通过
   └── 监控指标恢复正常

5. 记录与复盘
   └── 记录故障时间、原因、解决方案

7.3 紧急恢复命令¶

# 紧急重启所有服务
docker compose -f docker-compose.prod.yml restart

# 紧急重建 API
docker compose -f docker-compose.prod.yml up -d --build --force-recreate api

# 紧急数据恢复
# 1. 停止 API
docker compose -f docker-compose.prod.yml stop api
# 2. 恢复数据
cat backup.sql | docker exec -i dip1-prod-postgres psql -U dip1_prod -d dip1_prod
# 3. 启动 API
docker compose -f docker-compose.prod.yml start api

# 完全重置（⚠️ 仅限测试环境）
docker compose -f docker-compose.prod.yml down -v
docker compose -f docker-compose.prod.yml up -d --build
docker exec dip1-api-1 alembic upgrade head
docker exec dip1-api-1 python -m app.infrastructure.db.seed.cli

八、安全规范¶

8.1 访问控制¶

API 访问
所有 API 必须通过 HTTPS 访问
管理后台仅允许内网 / VPN 访问
实施 IP 白名单（可选）
数据库访问
仅允许 API 容器内网访问
禁止公网暴露数据库端口
使用强密码，定期轮换
Redis 访问
仅允许 API 容器内网访问
生产环境设置密码认证

8.2 密钥安全¶

存储
所有密钥存储在环境变量，禁止硬编码
.env.prod 文件加入 .gitignore
使用密钥管理服务（如 AWS Secrets Manager / HashiCorp Vault）
轮换
JWT 密钥：每 90 天
数据库密码：每 180 天
R2 存储密钥：每 90 天
审计
记录所有密钥变更操作
变更前备份旧密钥，支持过渡期间双密钥

8.3 数据安全¶

备份
每日自动备份
异地存储（可选）
保留最近 30 天备份
加密
传输层：TLS 1.2+
存储层：敏感字段加密（如手机号、地址）
应用层：JWT Token 签名验证
审计日志
记录所有敏感操作（登录、数据修改、权限变更）
保留至少 1 年

九、更新与升级¶

9.1 版本更新流程¶

1. 准备阶段
   ├── 代码合并到 main 分支
   ├── 运行完整测试
   └── 生成新版本号

2. 构建阶段
   ├── 构建新镜像: docker compose -f docker-compose.prod.yml build
   ├── 推送镜像仓库（如 Docker Hub / 私有仓库）
   └── 镜像打标签

3. 部署阶段
   ├── 数据库迁移: docker exec dip1-api-1 alembic upgrade head
   ├── 更新容器: docker compose -f docker-compose.prod.yml up -d --no-deps
   └── 健康检查: curl http://localhost:8000/health

4. 验证阶段
   ├── 核心功能冒烟测试
   ├── 性能回归测试
   └── 监控指标验证

5. 回滚方案（如验证失败）
   └── docker compose -f docker-compose.prod.yml up -d --no-deps （使用旧镜像标签）

9.2 数据库变更¶

# 创建新迁移
cd dip1/backend
alembic revision -m "描述变更内容"

# 编写迁移脚本（修改 upgrade/downgrade 函数）

# 部署时执行
docker exec dip1-api-1 alembic upgrade head

# 回滚（如迁移失败）
docker exec dip1-api-1 alembic downgrade -1

9.3 配置变更¶

# 1. 修改 .env.prod
# 2. 重启 API 服务使配置生效
docker compose -f docker-compose.prod.yml up -d --no-deps api

# ⚠️ 注意：仅修改环境变量无需重建镜像

十、附录¶

10.1 常用命令速查¶

操作	命令
启动所有服务	`docker compose -f docker-compose.prod.yml --env-file .env.prod up -d`
停止所有服务	`docker compose -f docker-compose.prod.yml down`
查看服务状态	`docker compose -f docker-compose.prod.yml ps`
查看 API 日志	`docker logs dip1-api-1 --tail 100`
重启 API	`docker compose -f docker-compose.prod.yml restart api`
健康检查	`curl http://localhost:8000/health`
数据库迁移	`docker exec dip1-api-1 alembic upgrade head`
种子数据	`docker exec dip1-api-1 python -m app.infrastructure.db.seed.cli`
数据库备份	`docker exec dip1-prod-postgres pg_dump -U dip1_prod dip1_prod > backup.sql`
清理所有容器	`docker compose -f docker-compose.prod.yml down -v`

10.2 端口清单¶

服务	端口	内部访问	外部访问
API	8000	✅	✅（需 HTTPS 代理）
PostgreSQL	5432	✅	❌
Redis	6379	✅	❌

10.3 服务账户¶

账户	用途	权限
dip1_prod	API 访问数据库	SELECT, INSERT, UPDATE, DELETE
TL 角色	管理员角色	全部权限
OL 角色	运营角色	业务权限
WKR 角色	师傅角色	订单权限
CST 角色	客户角色	查看权限

10.4 文档索引¶

文档	路径	说明
DIP1-ARC 架构设计	`docs/DIP1-ARC-架构设计.md`	系统架构、ADR 决策
DIP1-P2 一线操作系统	`docs/DIP1-P2-一线操作系统设计.md`	API 设计、数据模型
DIP1-P3 技术基础设施	`docs/DIP1-P3-技术基础设施.md`	开发环境、CI/CD
DIP1-SPEC 需求规格	`docs/DIP1-SPEC-需求规格说明书.md`	功能需求、用户故事
DIP1-IMP 实施指南	`docs/DIP1-IMP-Code-Agent实施指南.md`	项目计划、验收标准
生产部署报告	`docs/worklog/20260811_08_生产环境部署完成报告.md`	部署记录

修订记录¶

版本	日期	修订人	修订内容
V1.0	2026-08-11	DT	初始版本，生产环境管理员操作手册

本手册为 DIP1 生产环境运维文档，由听写 DT 维护。
技术支持：TL / DT
最后更新：2026-08-11