一刻工坊｜部署手册 V2.0

文档目标：指导运维/开发人员完成从本地到生产环境的部署 最后更新：2025-12-22 依据：Based on /docs/_source_of_truth/tech_facts.md

1. 基础环境要求

1.1 硬件/云资源

[ ] 域名: 一个备案完成的一级/二级域名 (e.g., api.yike.com).
[ ] HTTPS 证书: 泛域名证书或单域名证书 (Let's Encrypt / 阿里云).
[ ] 对象存储 (OSS): MinIO (私有化) 或 AWS S3 / 阿里云 OSS.
[ ] 数据库: PostgreSQL 14+.
[ ] 缓存/队列: Redis 6+ (用于 BullMQ 队列和 Session).
[ ] 计算资源:
- Backend Node: 2核 4G RAM (最低).
- Python Agent: 2核 8G RAM (建议).
- GPU (可选): 仅当部署 本地 ComfyUI 或 本地 LLM 时需要。
  - 推荐: NVIDIA RTX 3060 (12GB VRAM) 及以上.
  - 注：若使用 API 模式调用 Suno/Midjourney，则不需要本地 GPU。

1.2 软件依赖

[ ] Node.js: v18 LTS 或 v20 LTS.
[ ] Python: 3.10+ (用于 LangGraph).
[ ] PM2: 进程守护 (生产环境).
[ ] Docker & Compose: 容器化部署建议.
[ ] FFmpeg: 必须安装，用于音视频处理.
[ ] Nginx: Web 服务器和反向代理.

2. 部署模式详解

2.1 🏠 本地开发模式 (Local Dev)

适合开发调试，无需复杂依赖。

启动 DB/Redis: docker-compose up -d postgres redis
配置 .env: 复制 .env.example 为 .env，填入本地参数。

安装依赖:

bash

cd backend && npm install
cd ../frontend && npm install
cd ../langgraph-runner && pip install -r requirements.txt

启动 Backend: cd backend && npm run dev (Nodemon).
启动 Frontend: cd frontend && npm run dev (Vite).
启动 Agent: cd langgraph-runner && python app/main.py (Debug mode).

2.2 🧪 测试/预发模式 (Staging)

模拟生产环境，主要用于 CI/CD 验证。

[ ] 数据库使用独立的 Staging 库。
[ ] 第三方 API 使用 Sandbox/Mock Key (如有)。
[ ] 部署方式：Docker Compose 单机编排。

2.3 🚀 生产模式 (Production)

高可用，高性能。

[ ] 数据库: 云托管 PostgreSQL (RDS) + 主从高可用。
[ ] 缓存: 云托管 Redis Cluster。
[ ] Backend: PM2 Cluster 模式 (pm2 start ecosystem.config.js) 或 K8s Deployment。
[ ] Frontend: Nginx 托管静态资源 + CDN 加速。
[ ] Agent: 独立容器集群，配合 HPA 自动扩缩容。

3. 快速部署脚本

3.1 使用 deployment/ 目录脚本

项目根目录下的 deployment/ 包含完整的部署脚本：

脚本清单：

deployment/
├── 01-env-check.sh           # 环境检查与依赖安装
├── 02-deploy-backend.sh      # Backend 部署
├── 03-deploy-langgraph.sh    # LangGraph Agent 部署
├── 04-configure-nginx.sh     # Nginx 配置
├── 05-integration-test.sh    # 集成测试
├── deploy-all.sh              # 一键部署所有服务
├── update-deployment.sh       # Git 更新部署
├── verify-deployment.sh       # 验证部署状态
└── README.md                  # 详细说明

3.2 一键部署命令

首次部署：

bash

# 1. 上传代码到服务器
scp -r deployment/ root@your-server:/root/

# 2. SSH 登录服务器
ssh root@your-server

# 3. 赋予执行权限
chmod +x deployment/*.sh

# 4. 运行一键部署
cd /root/deployment
./deploy-all.sh

后续更新：

bash

# 通过 Git 拉取更新
./update-deployment.sh

3.3 脚本功能说明

01-env-check.sh：

检查 Node.js / Python / PostgreSQL / PM2 / Nginx
自动安装缺失的依赖
创建必要的目录

02-deploy-backend.sh：

安装 npm 依赖
运行数据库迁移
使用 PM2 启动服务

03-deploy-langgraph.sh：

创建 Python 虚拟环境
安装 pip 依赖
配置 Systemd 服务

04-configure-nginx.sh：

配置反向代理
配置 SSL 证书（Certbot）
重载 Nginx

05-integration-test.sh：

测试所有服务健康状态
测试 API 端点
生成测试报告

4. Docker Compose 部署

4.1 完整配置文件

创建 docker-compose.yml：

yaml

version: '3.8'

services:
  # PostgreSQL 数据库
  postgres:
    image: postgres:15-alpine
    container_name: kkmusic-postgres
    environment:
      POSTGRES_DB: kkmusic
      POSTGRES_USER: kkmusic_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kkmusic_user"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Redis 缓存
  redis:
    image: redis:7-alpine
    container_name: kkmusic-redis
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    ports:
      - "6379:6379"
    restart: always
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  # MinIO 对象存储
  minio:
    image: minio/minio:latest
    container_name: kkmusic-minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    volumes:
      - minio_data:/data
    ports:
      - "9000:9000"
      - "9001:9001"
    restart: always

  # Backend API
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    container_name: kkmusic-backend
    env_file: ./backend/.env
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "3001:3001"
    volumes:
      - ./backend/logs:/app/logs
      - ./backend/uploads:/app/uploads
    restart: always

  # LangGraph Agent
  langgraph:
    build:
      context: ./langgraph-runner
      dockerfile: Dockerfile
    container_name: kkmusic-langgraph
    env_file: ./langgraph-runner/.env
    depends_on:
      - postgres
      - redis
    ports:
      - "8000:8000"
    restart: always

  # Nginx 反向代理
  nginx:
    image: nginx:alpine
    container_name: kkmusic-nginx
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
      - ./frontend/dist:/usr/share/nginx/html:ro
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - backend
      - langgraph
    restart: always

volumes:
  postgres_data:
  redis_data:
  minio_data:

4.2 Dockerfile 示例

Backend Dockerfile：

dockerfile

FROM node:18-alpine

WORKDIR /app

# 安装依赖
COPY package*.json ./
RUN npm ci --only=production

# 复制代码
COPY . .

# 暴露端口
EXPOSE 3001

# 启动命令
CMD ["node", "src/index.js"]

LangGraph Dockerfile：

dockerfile

FROM python:3.10-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# 安装 Python 依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制代码
COPY app/ ./app/

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

4.3 启动命令

bash

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f backend

# 停止服务
docker-compose down

# 重启单个服务
docker-compose restart backend

5. Nginx 配置详解

5.1 主配置文件

nginx.conf：

nginx

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    access_log /var/log/nginx/access.log main;

    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml text/javascript 
               application/json application/javascript application/xml+rss;

    include /etc/nginx/conf.d/*.conf;
}

5.2 Backend API 反向代理

sites-available/api.conf：

nginx

# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name api.landi.asia;
    return 301 https://$server_name$request_uri;
}

# HTTPS 配置
server {
    listen 443 ssl http2;
    server_name api.landi.asia;

    # SSL 证书
    ssl_certificate /etc/nginx/ssl/api.landi.asia.crt;
    ssl_certificate_key /etc/nginx/ssl/api.landi.asia.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 日志
    access_log /var/log/nginx/api.access.log;
    error_log /var/log/nginx/api.error.log;

    # 客户端上传限制
    client_max_body_size 2G;
    client_body_timeout 300s;

    # 反向代理到 Backend
    location /api/ {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        
        # 代理头
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # 超时设置
        proxy_connect_timeout 60s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }

    # WebSocket 支持
    location /ws {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 静态文件（上传的素材）
    location /uploads/ {
        alias /var/www/kkmusic-backend/uploads/;
        expires 7d;
        add_header Cache-Control "public, immutable";
    }
}

5.3 LangGraph Agent 反向代理

sites-available/agent.conf：

nginx

server {
    listen 80;
    server_name agent.landi.asia;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name agent.landi.asia;

    ssl_certificate /etc/nginx/ssl/agent.landi.asia.crt;
    ssl_certificate_key /etc/nginx/ssl/agent.landi.asia.key;

    access_log /var/log/nginx/agent.access.log;
    error_log /var/log/nginx/agent.error.log;

    client_max_body_size 100M;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # AI 生成超时设置更长
        proxy_connect_timeout 120s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;
    }
}

5.4 Frontend 静态站点

sites-available/frontend.conf：

nginx

server {
    listen 80;
    server_name landi.asia www.landi.asia;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name landi.asia www.landi.asia;

    ssl_certificate /etc/nginx/ssl/landi.asia.crt;
    ssl_certificate_key /etc/nginx/ssl/landi.asia.key;

    root /var/www/kkmusic-frontend/dist;
    index index.html;

    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

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

    # Gzip 压缩
    gzip on;
    gzip_types text/css application/javascript application/json;
}

5.5 SSL 证书配置

使用 Certbot 自动申请：

bash

# 安装 Certbot
sudo apt install certbot python3-certbot-nginx

# 申请证书
sudo certbot --nginx -d api.landi.asia -d agent.landi.asia -d landi.asia

# 自动续期（添加到 crontab）
0 3 * * * certbot renew --quiet

6. 配置说明 (.env)

6.1 Backend 环境变量

创建 backend/.env：

bash

# === 基础配置 ===
NODE_ENV=production
PORT=3001
APP_SECRET=your_random_secret_key_here_min_32_chars

# === 数据库 ===
DB_HOST=localhost
DB_PORT=5432
DB_NAME=kkmusic
DB_USER=kkmusic_user
DB_PASSWORD=your_db_password_here

# === Redis ===
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password_here
REDIS_URL=redis://:${REDIS_PASSWORD}@${REDIS_HOST}:${REDIS_PORT}

# === 对象存储 ===
OSS_PROVIDER=minio  # minio, s3, aliyun
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=kkmusic

# === AI 服务 ===
OPENAI_API_KEY=sk-...
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_MODEL=gpt-4-turbo-preview

ZHENZHEN_API_KEY=your_zhenzhen_key
ZHENZHEN_API_BASE=https://api.zhenzhen.ai/v1
ZHENZHEN_MODEL=deepseek-chat

# === 音频/音乐 ===
SUNO_COOKIE=your_suno_cookie_here
FISH_API_TOKEN=your_fish_audio_token

# === ComfyUI ===
COMFYUI_HOST=http://localhost:8188
COMFYUI_ENABLED=true

# === 剪映 ===
JIANYING_DRAFT_PATH=/Users/username/Movies/JianyingPro/User Data/Projects/com.lveditor.draft

# === LangGraph ===
LANGGRAPH_API_URL=http://localhost:8000

# === 跨域 ===
ALLOWED_ORIGINS=https://landi.asia,http://localhost:5173

# === 日志 ===
LOG_LEVEL=info

6.2 LangGraph 环境变量

创建 langgraph-runner/.env：

bash

# === AI 服务 ===
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4-turbo-preview
OPENAI_API_BASE=https://api.openai.com/v1

# === 后端 API ===
NODE_API_URL=http://localhost:3001
NODE_API_TOKEN=your_internal_api_token

# === 服务配置 ===
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=info

7. 第三方 API 接入

7.1 核心生成服务

Suno (音乐):

在 .env 配置 SUNO_COOKIE
Cookie 获取方式：登录 suno.ai → 浏览器开发者工具 → Application → Cookies
需设置定时任务每 7 天刷新 Cookie 保活

Fish Audio (配音):

配置 FISH_API_TOKEN
注册地址：https://fish.audio
检查余额充足（建议充值 100 元起）

ComfyUI (图像/视频):

模式 A (本地): 配置 COMFYUI_HOST=http://localhost:8188
模式 B (云端): 配置 API Gateway 地址及 Token

7.2 客户端工具集成

剪映 (Jianying):

仅支持 Windows/Mac 本地环境
需配置 JIANYING_DRAFT_PATH 指向剪映草稿目录
注意：生产服务器环境通常无法运行剪映

7.3 支付与登录

支付宝:

bash

ALIPAY_APP_ID=your_app_id
ALIPAY_PRIVATE_KEY=your_private_key
ALIPAY_PUBLIC_KEY=alipay_public_key

微信支付:

bash

WECHAT_MCH_ID=your_mch_id
WECHAT_API_V3_KEY=your_api_v3_key
WECHAT_CERT_PATH=/path/to/cert.pem

微信登录:

bash

WX_OPEN_APP_ID=your_open_app_id
WX_OPEN_SECRET=your_open_secret

8. 数据库迁移

8.1 运行迁移

首次部署：

bash

cd backend
npm run db:migrate

迁移文件位置：backend/src/database/migrations/

8.2 迁移命令

bash

# 运行所有待执行迁移
npm run db:migrate

# 回滚最后一次迁移
npm run db:migrate:undo

# 查看迁移状态
npm run db:migrate:status

8.3 创建新迁移

bash

# 生成迁移文件
npx sequelize-cli migration:generate --name add-new-field

# 编辑迁移文件
# 在 migrations/ 目录找到生成的文件，编辑 up/down 方法

8.4 迁移示例

javascript

'use strict';

module.exports = {
  async up(queryInterface, Sequelize) {
    await queryInterface.addColumn('tasks', 'priority', {
      type: Sequelize.INTEGER,
      defaultValue: 0,
      allowNull: false
    });
  },

  async down(queryInterface, Sequelize) {
    await queryInterface.removeColumn('tasks', 'priority');
  }
};

9. 监控与告警

9.1 健康检查 (Health Check)

[ ] 接口: GET /health
[ ] 检查项: DB 连接、Redis 连接、磁盘空间。
[ ] 频率: 每 30s 一次。

健康检查响应：

json

{
  "status": "healthy",
  "timestamp": "2025-12-22T10:00:00Z",
  "services": {
    "database": { "status": "up", "latency": "2ms" },
    "redis": { "status": "up", "latency": "1ms" },
    "disk": { "status": "ok", "usage": "45%" },
    "memory": { "status": "ok", "usage": "60%" }
  }
}

9.2 关键指标 (Metrics)

建议集成 Prometheus + Grafana。

核心指标：

http_requests_total: API 请求量 (按 status code 分组)
http_request_duration_seconds: API 响应时间
task_queue_size: 待处理任务数 (堆积预警)
task_completion_time: 任务完成耗时
generation_success_rate: AI 生成成功率
db_connection_pool_active: 数据库连接池活跃连接数
redis_memory_usage: Redis 内存使用
gpu_utilization: GPU 利用率 (如有本地节点)

9.3 日志采集

[ ] 生产环境建议将日志输出到 stdout，由 Docker Driver 收集至 ELK 或 Loki。
[ ] 错误日志 (level=error) 需触发即时告警 (钉钉/飞书/邮件)。

日志级别：

debug: 调试信息（仅开发环境）
info: 正常操作日志
warn: 警告（可恢复的错误）
error: 错误（需要关注）
fatal: 致命错误（服务中断）

9.4 告警配置

钉钉 Webhook 告警：

javascript

// backend/src/utils/alert.js
const axios = require('axios');

async function sendDingTalkAlert(message) {
  const webhook = process.env.DINGTALK_WEBHOOK;
  await axios.post(webhook, {
    msgtype: 'text',
    text: {
      content: `【一刻工坊告警】\n${message}`
    }
  });
}

// 使用示例
if (taskFailureRate > 0.5) {
  await sendDingTalkAlert(`任务失败率过高: ${taskFailureRate * 100}%`);
}

10. 备份与恢复

10.1 数据库备份

每日全量备份：

bash

#!/bin/bash
# backup-db.sh

BACKUP_DIR=/backup/postgres
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE=$BACKUP_DIR/kkmusic_$DATE.sql

# 创建备份目录
mkdir -p $BACKUP_DIR

# 执行备份
pg_dump -U kkmusic_user kkmusic > $BACKUP_FILE

# 压缩备份
gzip $BACKUP_FILE

# 删除 7 天前的备份
find $BACKUP_DIR -name "*.gz" -mtime +7 -delete

echo "Backup completed: $BACKUP_FILE.gz"

添加到 crontab：

bash

# 每天凌晨 2 点执行备份
0 2 * * * /root/scripts/backup-db.sh >> /var/log/backup.log 2>&1

10.2 数据库恢复

bash

# 解压备份文件
gunzip kkmusic_20251222_020000.sql.gz

# 恢复数据库
psql -U kkmusic_user kkmusic < kkmusic_20251222_020000.sql

10.3 对象存储备份

[ ] 策略: 开启版本控制 (Versioning)，防止误删。
[ ] 跨区域复制 (CRR): 建议开启异地容灾。

MinIO 备份：

bash

# 使用 mc (MinIO Client) 同步到备份桶
mc mirror local/kkmusic backup/kkmusic-backup

10.4 配置文件备份

[ ] 策略: 使用 GitOps 管理配置模板，Secrets 使用 Vault 或云厂商 KMS 管理。

11. 故障排障 (Troubleshooting)

11.1 常见问题清单

现象	可能原因	排查命令/方案
Backend 启动失败	端口被占用 / 环境变量未配置	`lsof -i :3001` `pm2 logs backend`
队列堆积	Agent 消费慢 / 挂死	`pm2 log agent` 查看报错重启 Agent 增加 Consumer 数量
API 超时 (504)	数据库慢查询 / 同步调用了耗时操作	检查 Slow Query Log 将同步逻辑改为异步 Task
生成失败	第三方 API 欠费 / Token 过期	检查 `.env` 配置测试第三方连通性
Suno 401	Cookie 失效	手动更新 `.env` 中的 `SUNO_COOKIE` 并重启服务
PostgreSQL 连接失败	密码错误 / 防火墙 / 连接数耗尽	`psql -U kkmusic_user -h localhost` `SHOW max_connections;`
Redis 连接失败	密码错误 / Redis 未启动	`redis-cli -a password ping`
Nginx 502	Backend 未启动 / 端口错误	`pm2 status` `curl http://localhost:3001/health`
文件上传失败	MinIO 未启动 / 权限问题	检查 MinIO 日志 `mc admin info local`

11.2 日志分析技巧

查看实时日志：

bash

# PM2 管理的服务
pm2 logs backend --lines 100

# Systemd 管理的服务
journalctl -u kkmusic-langgraph -f

# Docker 容器
docker logs -f kkmusic-backend

# Nginx 日志
tail -f /var/log/nginx/error.log

搜索错误日志：

bash

# 查找特定错误
grep "ERROR" /var/log/kkmusic/backend.log | tail -20

# 按时间筛选
grep "2025-12-22 10:" /var/log/kkmusic/backend.log

11.3 性能排查

数据库慢查询：

sql

-- 查看慢查询
SELECT query, calls, total_time, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

-- 查看当前活跃连接
SELECT * FROM pg_stat_activity WHERE state = 'active';

Redis 性能：

bash

# 查看 Redis 信息
redis-cli info stats

# 查看慢查询
redis-cli slowlog get 10

11.4 限流与降级

限流: Nginx 层配置 IP 限流：

nginx

# 限制单 IP 每秒 10 个请求
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

server {
    location /api/ {
        limit_req zone=api_limit burst=20 nodelay;
        proxy_pass http://localhost:3001;
    }
}

降级: 当 Suno 不可用时，自动切换至备用音乐库或静音模式，并提示用户。

12. 快速命令参考

12.1 服务管理

bash

# PM2
pm2 start ecosystem.config.js   # 启动
pm2 restart backend              # 重启
pm2 stop backend                 # 停止
pm2 logs backend                 # 查看日志
pm2 monit                        # 监控面板

# Systemd
systemctl start kkmusic-langgraph
systemctl stop kkmusic-langgraph
systemctl restart kkmusic-langgraph
systemctl status kkmusic-langgraph

# Nginx
nginx -t                         # 测试配置
systemctl reload nginx           # 重载配置
systemctl restart nginx          # 重启

12.2 数据库操作

bash

# 连接数据库
psql -U kkmusic_user -d kkmusic

# 备份数据库
pg_dump -U kkmusic_user kkmusic > backup.sql

# 恢复数据库
psql -U kkmusic_user kkmusic < backup.sql

# 查看表大小
SELECT pg_size_pretty(pg_total_relation_size('tasks'));

12.3 容器操作

bash

# Docker Compose
docker-compose up -d             # 启动
docker-compose down              # 停止
docker-compose restart backend   # 重启单个服务
docker-compose logs -f backend   # 查看日志
docker-compose exec backend sh   # 进入容器

版本记录：

V1.0 (2025-12-21): 初始版本，基础部署说明
V2.0 (2025-12-22): 完整版本，新增快速部署脚本、Docker Compose 完整配置、Nginx 详细配置、数据库迁移、日志分析、快速命令参考

一刻工坊｜部署手册 V2.0 ​

目录 ​

1. 基础环境要求 ​

1.1 硬件/云资源 ​

1.2 软件依赖 ​

2. 部署模式详解 ​

2.1 🏠 本地开发模式 (Local Dev) ​

2.2 🧪 测试/预发模式 (Staging) ​

2.3 🚀 生产模式 (Production) ​

3. 快速部署脚本 ​

3.1 使用 deployment/ 目录脚本 ​

3.2 一键部署命令 ​

3.3 脚本功能说明 ​

4. Docker Compose 部署 ​

4.1 完整配置文件 ​

4.2 Dockerfile 示例 ​

4.3 启动命令 ​

5. Nginx 配置详解 ​

5.1 主配置文件 ​

5.2 Backend API 反向代理 ​

5.3 LangGraph Agent 反向代理 ​

5.4 Frontend 静态站点 ​

5.5 SSL 证书配置 ​

6. 配置说明 (.env) ​

6.1 Backend 环境变量 ​

6.2 LangGraph 环境变量 ​

7. 第三方 API 接入 ​

7.1 核心生成服务 ​

7.2 客户端工具集成 ​

7.3 支付与登录 ​

8. 数据库迁移 ​

8.1 运行迁移 ​

8.2 迁移命令 ​

8.3 创建新迁移 ​

8.4 迁移示例 ​

9. 监控与告警 ​

9.1 健康检查 (Health Check) ​

9.2 关键指标 (Metrics) ​

9.3 日志采集 ​

9.4 告警配置 ​

10. 备份与恢复 ​

10.1 数据库备份 ​

10.2 数据库恢复 ​

10.3 对象存储备份 ​

10.4 配置文件备份 ​

11. 故障排障 (Troubleshooting) ​

11.1 常见问题清单 ​

11.2 日志分析技巧 ​

11.3 性能排查 ​

11.4 限流与降级 ​

12. 快速命令参考 ​

12.1 服务管理 ​

12.2 数据库操作 ​

12.3 容器操作 ​

一刻工坊｜部署手册 V2.0

目录

1. 基础环境要求

1.1 硬件/云资源

1.2 软件依赖

2. 部署模式详解

2.1 🏠 本地开发模式 (Local Dev)

2.2 🧪 测试/预发模式 (Staging)

2.3 🚀 生产模式 (Production)

3. 快速部署脚本

3.1 使用 deployment/ 目录脚本

3.2 一键部署命令

3.3 脚本功能说明

4. Docker Compose 部署

4.1 完整配置文件

4.2 Dockerfile 示例

4.3 启动命令

5. Nginx 配置详解

5.1 主配置文件

5.2 Backend API 反向代理

5.3 LangGraph Agent 反向代理

5.4 Frontend 静态站点

5.5 SSL 证书配置

6. 配置说明 (.env)

6.1 Backend 环境变量

6.2 LangGraph 环境变量

7. 第三方 API 接入

7.1 核心生成服务

7.2 客户端工具集成

7.3 支付与登录

8. 数据库迁移

8.1 运行迁移

8.2 迁移命令

8.3 创建新迁移

8.4 迁移示例

9. 监控与告警

9.1 健康检查 (Health Check)

9.2 关键指标 (Metrics)

9.3 日志采集

9.4 告警配置

10. 备份与恢复

10.1 数据库备份

10.2 数据库恢复

10.3 对象存储备份

10.4 配置文件备份

11. 故障排障 (Troubleshooting)

11.1 常见问题清单

11.2 日志分析技巧

11.3 性能排查

11.4 限流与降级

12. 快速命令参考

12.1 服务管理

12.2 数据库操作

12.3 容器操作