life-echo/api/docs/部署指南.md

短信验证码功能部署指南

概述

本文档说明如何在生产环境中部署短信验证码功能，包括环境配置、数据库迁移、服务配置等。

前置条件

1. PostgreSQL 数据库已安装并运行
2. Redis 服务已安装并运行
3. 已注册腾讯云账号并开通短信服务
4. 已获取腾讯云短信服务凭证

部署步骤

1. 腾讯云短信服务配置

1.1 登录腾讯云控制台

访问：https://console.cloud.tencent.com/smsv2

1.2 创建短信应用

1. 进入"应用管理"
2. 点击"创建应用"
3. 填写应用名称（如：Life Echo）
4. 记录生成的 SDK AppID

1.3 配置短信签名

1. 进入"国内短信" -> "签名管理"
2. 点击"创建签名"
3. 填写签名内容（如：【人生回响】）
4. 选择签名类型（如：App）
5. 上传相关证明材料
6. 等待审核通过

1.4 配置短信模板

创建一个通用的验证码模板（所有场景共用）：

验证码模板：

【人生回响】您的验证码是：{1}，有效期{2}分钟，请勿泄露给他人。

模板参数说明：

• {1} - 验证码（6位数字）
• {2} - 有效期（分钟数，如：5）

注意： 所有场景（注册、登录、重置密码、修改手机号）共用同一个模板。

记录模板ID。

1.5 获取API密钥

1. 访问：https://console.cloud.tencent.com/cam/capi
2. 点击"新建密钥"
3. 记录 SecretId 和 SecretKey
4. 重要：妥善保管密钥，不要泄露

2. 环境变量配置

配置分两层，详见 configuration.md：

• .env（secrets + bootstrap）：数据库/Redis 连接串、SECRET_KEY、腾讯云 API 密钥等
• config/{APP_ENV}.toml（非密钥）：SMS 应用 ID/签名/模板、JWT 过期时间、CORS 等

2.1 编辑生产环境配置文件

编辑 api/.env.production（密钥与连接串）：

APP_ENV=production
DATABASE_URL=postgresql://username:password@host:5432/life_echo

# Redis（业务 DB/0；Celery broker/backend 使用 DB/1）
REDIS_URL=redis://redis:6379/0
REDIS_PASSWORD=your_redis_password_here
# 生产 compose 已显式注入；本地或自定义部署请设：
CELERY_REDIS_URL=redis://:your_redis_password_here@redis:6379/1
# 升级至 DB 分离后，DB/0 上未消费的 Celery 队列会被丢弃（一次性 cutover）。
# REDIS_URL 使用 DB/15 时必须显式设置 CELERY_REDIS_URL（无法 auto DB+1）。

# Auth（生产务必：openssl rand -hex 32）
SECRET_KEY=your_strong_random_secret_here

# 腾讯云 API 密钥（SMS / ASR / TTS / COS 共用）
TENCENT_SECRET_ID=your_secret_id_here
TENCENT_SECRET_KEY=your_secret_key_here
# ASR 录音文件识别极速版必填（API 密钥管理页 AppId）
TENCENT_APP_ID=your_app_id_here

编辑 api/config/production.toml（SMS 业务 ID 等非密钥项）：

[deploy]
tencent_sms_sdk_app_id = "1400xxxxxx"
tencent_sms_sign_name = "人生回响"
tencent_sms_template_id = "123456"
api_cors_origins = "https://your-domain.com"
access_token_expire_minutes = 30
refresh_token_expire_days = 7

2.2 配置说明

配置项	层级	说明	示例
SECRET_KEY	.env	JWT 签名密钥	openssl rand -hex 32 输出
TENCENT_SECRET_ID	.env	腾讯云 API 密钥 ID	AKIDxxxxxxxxxxxxx
TENCENT_SECRET_KEY	.env	腾讯云 API 密钥 Key	xxxxxxxxxxxxxxxx
TENCENT_APP_ID	.env	腾讯云 AppId（ASR 极速版）	1259220000
tencent_sms_sdk_app_id	config/production.toml	短信应用 ID	1400xxxxxx
tencent_sms_sign_name	config/production.toml	短信签名（不含【】）	人生回响
tencent_sms_template_id	config/production.toml	短信模板 ID（所有场景共用）	123456
api_cors_origins	config/production.toml	浏览器跨域允许来源（逗号分隔）	https://lifecho.worldsplats.com
access_token_expire_minutes	config/production.toml	Access token 有效期（分钟）	30
refresh_token_expire_days	config/production.toml	Refresh token 有效期（天）	7

3. 数据库迁移

3.1 备份数据库

# 备份现有数据库
pg_dump -U postgres -d life_echo > backup_$(date +%Y%m%d_%H%M%S).sql

3.2 执行迁移脚本

# 方式1：使用psql命令
psql -U postgres -d life_echo -f api/migrations/add_sms_verification.sql

# 方式2：使用数据库管理工具
# 打开 pgAdmin 或其他工具，执行 add_sms_verification.sql 中的SQL语句

3.3 验证迁移结果

-- 检查表是否创建成功
SELECT * FROM information_schema.tables 
WHERE table_name = 'sms_verification_codes';

-- 检查索引是否创建成功
SELECT indexname FROM pg_indexes 
WHERE tablename = 'sms_verification_codes';

-- 检查 refresh_tokens 表是否添加了 device_info 字段
SELECT column_name, data_type 
FROM information_schema.columns 
WHERE table_name = 'refresh_tokens' AND column_name = 'device_info';

4. 依赖安装

4.1 更新Python依赖

cd api
pip install -r requirements.txt

确保 requirements.txt 中包含：

tencentcloud-sdk-python>=3.0.1000

4.2 验证依赖安装

python -c "from tencentcloud.sms.v20210111 import sms_client; print('腾讯云SDK安装成功')"

5. 服务部署

5.1 使用Docker部署

编辑 api/docker-compose.yml，添加环境变量：

version: '3.8'

services:
  api:
    build: .
    ports:
      - "8000:8000"
    env_file:
      - .env
    environment:
      - APP_ENV=production
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      - REDIS_PASSWORD=${REDIS_PASSWORD}
      - SECRET_KEY=${SECRET_KEY}
      - TENCENT_SECRET_ID=${TENCENT_SECRET_ID}
      - TENCENT_SECRET_KEY=${TENCENT_SECRET_KEY}
    depends_on:
      - postgres
      - redis
    restart: unless-stopped

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=life_echo
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7
    restart: unless-stopped

volumes:
  postgres_data:

启动服务：

cd api
docker compose up -d

5.2 使用Systemd部署

创建服务文件 /etc/systemd/system/life-echo-api.service：

[Unit]
Description=Life Echo API Service
After=network.target postgresql.service redis.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/life-echo/api
Environment="PATH=/path/to/venv/bin"
EnvironmentFile=/path/to/life-echo/api/.env.production
ExecStart=/path/to/venv/bin/python main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable life-echo-api
sudo systemctl start life-echo-api
sudo systemctl status life-echo-api

6. GitHub Actions配置

如果使用GitHub Actions自动部署，需要配置Secrets：

1. 进入GitHub仓库 -> Settings -> Secrets and variables -> Actions
2. 添加以下Secrets：

Secret名称	说明
SECRET_KEY	JWT 签名密钥
TENCENT_SECRET_ID	腾讯云 API 密钥 ID
TENCENT_SECRET_KEY	腾讯云 API 密钥 Key
DATABASE_URL	数据库连接串
REDIS_PASSWORD	Redis 密码（若启用）

SMS 应用 ID、签名、模板 ID 等非密钥项在 config/production.toml 的 [deploy] 中维护，随代码发版。

参考文档：github-actions-secrets.md

7. 验证部署

7.1 健康检查

curl http://localhost:8000/health

预期响应：

{
  "status": "healthy"
}

7.2 测试发送验证码

curl -X POST http://localhost:8000/api/auth/sms/send \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800138000",
    "purpose": "register"
  }'

预期响应：

{
  "message": "验证码已发送",
  "expires_in": 300
}

7.3 检查日志

# Docker部署
docker compose logs -f api

# Systemd部署
sudo journalctl -u life-echo-api -f

8. 监控与告警

本地开发与预发可观测性栈（OpenTelemetry + Grafana LGTM）见 可观测性指南。staging/production 全量接入为第二阶段（docker-compose profile）。

8.1 配置日志监控

建议使用以下工具：

• Grafana + Loki + Tempo + Prometheus（仓库内 deploy/observability/，推荐）
• ELK Stack (Elasticsearch + Logstash + Kibana)
• 云服务商的日志服务

8.2 配置性能监控

监控指标：

• API响应时间
• 短信发送成功率
• 验证码验证成功率
• 数据库查询性能
• Redis连接状态

8.3 配置告警

告警规则：

• 短信发送失败率 > 5%
• API响应时间 > 2秒
• 数据库连接失败
• Redis连接失败
• 磁盘空间 < 20%

9. 安全加固

9.1 防火墙配置

# 仅允许必要的端口
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable

9.2 SSL证书配置

使用Let's Encrypt免费证书：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d api.your-domain.com

9.3 限流配置

在Nginx中配置限流：

limit_req_zone $binary_remote_addr zone=sms_limit:10m rate=1r/m;

location /api/auth/sms/send {
    limit_req zone=sms_limit burst=2 nodelay;
    proxy_pass http://localhost:8000;
}

10. 备份与恢复

10.1 数据库备份

设置自动备份：

# 创建备份脚本
cat > /usr/local/bin/backup-db.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/var/backups/postgresql"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
pg_dump -U postgres -d life_echo | gzip > $BACKUP_DIR/life_echo_$DATE.sql.gz
# 保留最近7天的备份
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete
EOF

chmod +x /usr/local/bin/backup-db.sh

# 添加到crontab（每天凌晨2点执行）
echo "0 2 * * * /usr/local/bin/backup-db.sh" | crontab -

10.2 数据恢复

# 恢复数据库
gunzip < backup_file.sql.gz | psql -U postgres -d life_echo

11. 故障排查

11.1 短信发送失败

检查步骤：

1. 验证环境变量与 TOML 配置

echo $TENCENT_SECRET_ID
# SMS 业务 ID 见 config/production.toml [deploy] tencent_sms_sdk_app_id

2. 检查腾讯云账户余额

3. 查看后端日志

grep "SMS" /var/log/life-echo-api.log

4. 测试API连接

from tencentcloud.common import credential
from tencentcloud.sms.v20210111 import sms_client

cred = credential.Credential(SECRET_ID, SECRET_KEY)
client = sms_client.SmsClient(cred, "ap-guangzhou")

11.2 验证码验证失败

检查步骤：

1. 查询数据库中的验证码记录

SELECT * FROM sms_verification_codes 
WHERE phone = '13800138000' 
ORDER BY created_at DESC 
LIMIT 5;

2. 检查验证码是否过期
3. 检查验证码是否已使用
4. 检查用途是否匹配

11.3 数据库连接失败

检查步骤：

1. 验证数据库服务状态

sudo systemctl status postgresql

2. 检查数据库连接配置

psql -U postgres -d life_echo -c "SELECT 1"

3. 查看数据库日志

sudo tail -f /var/log/postgresql/postgresql-15-main.log

12. 性能优化

12.1 数据库优化

-- 分析表统计信息
ANALYZE sms_verification_codes;

-- 查看慢查询
SELECT * FROM pg_stat_statements 
WHERE query LIKE '%sms_verification_codes%' 
ORDER BY total_time DESC;

12.2 Redis优化

# 配置Redis持久化
redis-cli CONFIG SET save "900 1 300 10 60 10000"

# 设置最大内存
redis-cli CONFIG SET maxmemory 256mb
redis-cli CONFIG SET maxmemory-policy allkeys-lru

12.3 应用优化

• 使用连接池
• 启用缓存
• 异步发送短信
• 批量清理过期验证码

13. 定期维护

13.1 清理过期验证码

创建定时任务：

-- 创建清理函数
CREATE OR REPLACE FUNCTION cleanup_expired_sms_codes()
RETURNS void AS $$
BEGIN
    DELETE FROM sms_verification_codes
    WHERE expires_at < NOW() - INTERVAL '1 day';
END;
$$ LANGUAGE plpgsql;

-- 每天凌晨3点执行（使用pg_cron扩展）
SELECT cron.schedule('cleanup-sms', '0 3 * * *', 'SELECT cleanup_expired_sms_codes()');

13.2 监控数据库大小

SELECT 
    pg_size_pretty(pg_total_relation_size('sms_verification_codes')) as table_size,
    (SELECT count(*) FROM sms_verification_codes) as record_count;

部署检查清单

• 腾讯云短信服务已配置
• 环境变量已正确设置
• 数据库迁移已执行
• 依赖包已安装
• 服务已启动并运行
• 健康检查通过
• 发送验证码测试通过
• 日志正常输出
• 监控已配置
• 告警已配置
• 备份已配置
• SSL证书已配置
• 防火墙已配置
• 限流已配置

回滚计划

如果部署出现问题，执行以下步骤回滚：

1. 停止新版本服务

docker compose down
# 或
sudo systemctl stop life-echo-api

2. 恢复数据库

psql -U postgres -d life_echo < backup_file.sql

3. 切换到旧版本代码

git checkout previous-version

4. 重启服务

docker compose up -d
# 或
sudo systemctl start life-echo-api

联系支持

如有问题，请联系：

• 技术支持邮箱：support@your-domain.com
• 开发团队：dev@your-domain.com

更新日志

• 2024-01-XX: 初始版本
• 添加短信验证码功能
• 添加账户管理功能