JY API Docker 部署指南

本文档介绍如何使用 Docker 部署 JY API 服务。

🚀 快速开始

1. 准备环境变量

复制环境变量示例文件：

cp env.example .env

编辑 .env 文件，配置以下关键参数：

# 阿里云 OSS 配置（必需）
OSS_REGION=oss-cn-shanghai
OSS_ACCESS_KEY_ID=your_actual_access_key_id
OSS_ACCESS_KEY_SECRET=your_actual_access_key_secret
OSS_BUCKET=your_actual_bucket_name

# AES 加密密钥（建议更改）
AES_KEY=your_32_character_encryption_key
AES_IV=your_16_character_iv

2. 使用便捷脚本（推荐）

# 构建镜像
./scripts/docker-build.sh build

# 运行容器
./scripts/docker-build.sh run

# 查看日志
./scripts/docker-build.sh logs

# 重启服务
./scripts/docker-build.sh restart

3. 使用 Docker Compose

# 构建并启动服务
docker-compose up -d --build

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

4. 手动 Docker 命令

# 构建镜像
docker build -t jy-api:latest .

# 运行容器
docker run -d \
  --name jy-api-server \
  -p 3000:3000 \
  --env-file .env \
  -v "$(pwd)/logs:/app/logs" \
  --restart unless-stopped \
  jy-api:latest

📋 服务验证

启动后访问以下地址验证服务：

• API 首页: http://localhost:3000
• 健康检查: http://localhost:3000/health
• API 文档: http://localhost:3000/docs
• 示例接口: http://localhost:3000/api/drafts/create_draft

🔧 Docker 镜像特性

基础镜像

• Node.js 20 Alpine: 轻量级 Linux 发行版
• 多阶段构建: 优化镜像大小
• 非 root 用户: 提高安全性

安全特性

• 使用非特权用户运行
• 最小化系统依赖
• 健康检查机制
• 自动重启策略

性能优化

• 生产环境依赖安装
• npm 缓存清理
• 压缩和缓存中间件

📊 容器管理

查看容器状态

docker ps -a

查看实时日志

docker logs -f jy-api-server

进入容器调试

docker exec -it jy-api-server sh

查看资源使用

docker stats jy-api-server

🗂️ 目录结构

/app/                    # 容器工作目录
├── controllers/         # 控制器文件
├── routes/             # 路由文件
├── utils/              # 工具函数
├── middleware/         # 中间件
├── config/             # 配置文件
├── scripts/            # 脚本文件
├── logs/               # 日志文件（挂载）
├── *.md               # API 文档
├── app.js             # 主应用文件
└── package.json       # 依赖配置

🔒 环境变量说明

变量名	说明	必需
NODE_ENV	运行环境	否
PORT	服务端口	否
OSS_REGION	阿里云 OSS 区域	是
OSS_ACCESS_KEY_ID	OSS 访问密钥 ID	是
OSS_ACCESS_KEY_SECRET	OSS 访问密钥	是
OSS_BUCKET	OSS 存储桶名称	是
AES_KEY	AES 加密密钥	是
AES_IV	AES 初始化向量	是

🛠️ 故障排除

1. 容器启动失败

# 查看详细日志
docker logs jy-api-server

# 检查环境变量
docker exec jy-api-server env | grep -E "(OSS|AES)"

2. 端口冲突

# 查看端口占用
lsof -i :3000

# 更改映射端口
docker run -p 8080:3000 jy-api:latest

3. 依赖安装问题

# 重新构建镜像（无缓存）
docker build --no-cache -t jy-api:latest .

4. 权限问题

# 检查文件权限
docker exec jy-api-server ls -la /app

🚀 生产环境部署

使用反向代理

推荐使用 Nginx 作为反向代理：

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        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;
    }
}

使用 HTTPS

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

# 获取 SSL 证书
sudo certbot --nginx -d your-domain.com

监控和日志

# 设置日志轮转
echo "/app/logs/*.log {
    daily
    rotate 30
    compress
    missingok
    notifempty
    copytruncate
}" > /etc/logrotate.d/jy-api

# 使用 systemd 管理
sudo systemctl enable docker
sudo systemctl start docker

📈 性能调优

Docker 资源限制

docker run -d \
  --name jy-api-server \
  --memory="512m" \
  --cpus="1.0" \
  -p 3000:3000 \
  jy-api:latest

多实例负载均衡

# docker-compose.yml
version: '3.8'
services:
  jy-api-1:
    build: .
    ports: ["3001:3000"]
  jy-api-2:
    build: .
    ports: ["3002:3000"]
  jy-api-3:
    build: .
    ports: ["3003:3000"]

🔄 更新部署

# 停止旧容器
docker stop jy-api-server
docker rm jy-api-server

# 更新代码
git pull origin main

# 重新构建和运行
./scripts/docker-build.sh build
./scripts/docker-build.sh run

🆘 支持

如遇问题，请检查：

1. 日志文件: docker logs jy-api-server
2. 健康检查: curl http://localhost:3000/health
3. 容器状态: docker inspect jy-api-server
4. 网络连接: docker network ls

---

🎉 恭喜！您的 JY API 服务现已通过 Docker 成功部署！