API/DOCKER_DEPLOYMENT.md

NewAPI Docker 本地部署指南

概述

本指南介绍如何使用Docker部署修改后的NewAPI本地版本，而不是使用远程仓库的镜像。

文件说明

主要文件

• Dockerfile - Docker镜像构建文件
• docker-compose.local.yml - 本地构建版本的Docker Compose配置
• docker-compose.yml - 修改后的Docker Compose配置（使用本地构建）
• .dockerignore - Docker构建时忽略的文件
• build-and-deploy.sh - 自动化构建和部署脚本

版本文件

• VERSION - 包含自定义版本号 v1.0.0-custom

快速部署

方法一：使用自动化脚本（推荐）

# 运行自动化构建和部署脚本
./build-and-deploy.sh

方法二：手动部署

# 1. 构建并启动服务
docker-compose -f docker-compose.local.yml up -d --build

# 2. 查看服务状态
docker-compose -f docker-compose.local.yml ps

# 3. 查看日志
docker-compose -f docker-compose.local.yml logs -f new-api

服务配置

开发环境配置

端口映射

• NewAPI: 3000:3000
• MySQL: 3306:3306 (默认未暴露，如需外部访问请取消注释)

数据持久化

• 应用数据: ./data:/data
• 日志文件: ./logs:/app/logs
• MySQL数据: Docker volume mysql_data

环境变量

• TZ=Asia/Shanghai - 时区设置

生产环境配置 ⚠️

重要安全提醒

当前的 docker-compose.yml 和 docker-compose.local.yml 使用了默认密码，不适合生产环境！

生产环境部署文件

• docker-compose.prod.yml - 生产环境专用配置
• env.prod.example - 生产环境变量模板
• deploy-prod.sh - 自动化生产部署脚本

生产环境安全特性

1. 强密码要求: 所有密码通过环境变量配置
2. 网络隔离: 数据库和Redis不对外暴露端口
3. 健康检查: 完整的服务健康监控
4. 权限控制: MySQL用户权限最小化
5. 数据持久化: 独立的数据卷管理
6. 会话安全: 必须配置SESSION_SECRET

• ERROR_LOG_ENABLED=true - 启用错误日志
• SQL_DSN=root:123456@tcp(mysql:3306)/new-api - MySQL连接字符串
• REDIS_CONN_STRING=redis://redis - Redis连接字符串

自定义修改

本部署包含以下界面修改：

1. 侧边栏权限控制

   • 普通用户无法看到"操练场"和"聊天"功能
   • 管理员用户保留完整权限

2. 导航栏简化

   • 隐藏"文档"和"关于"按钮
   • 保留核心导航功能

3. 首页优化

   • 隐藏"获取密钥"和"文档"按钮

4. Footer移除

   • 完全隐藏页面底部区域

管理命令

查看服务状态

docker-compose -f docker-compose.local.yml ps

查看日志

# 查看所有服务日志
docker-compose -f docker-compose.local.yml logs

# 实时查看NewAPI日志
docker-compose -f docker-compose.local.yml logs -f new-api

# 查看MySQL日志
docker-compose -f docker-compose.local.yml logs mysql

重启服务

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

# 仅重启NewAPI服务
docker-compose -f docker-compose.local.yml restart new-api

停止服务

docker-compose -f docker-compose.local.yml down

完全清理

# 停止并删除所有容器、网络
docker-compose -f docker-compose.local.yml down

# 删除数据卷（注意：会丢失所有数据）
docker-compose -f docker-compose.local.yml down -v

# 清理未使用的镜像
docker image prune -f

故障排除

常见问题

1. 端口冲突

   • 确保3000端口未被其他服务占用
   • 可以修改docker-compose.local.yml中的端口映射

2. 构建失败

   • 检查Docker和Docker Compose版本
   • 确保有足够的磁盘空间
   • 查看构建日志：docker-compose -f docker-compose.local.yml build --no-cache

3. 服务启动失败

   • 查看容器日志：docker-compose -f docker-compose.local.yml logs new-api
   • 检查数据库连接配置
   • 确保MySQL服务正常启动

4. 数据库连接问题

   • 等待MySQL完全启动（通常需要30-60秒）
   • 检查数据库密码配置是否一致
   • 查看MySQL日志：docker-compose -f docker-compose.local.yml logs mysql

健康检查

NewAPI服务包含健康检查，每30秒检查一次服务状态：

# 手动检查服务健康状态
curl http://localhost:3000/api/status

性能优化

1. 资源限制

   • 可在docker-compose.local.yml中添加内存和CPU限制

2. 缓存优化

   • 启用Redis缓存以提高性能
   • 配置适当的缓存策略

更新部署

当代码有更新时：

# 方法一：使用脚本（推荐）
./build-and-deploy.sh

# 方法二：手动更新
docker-compose -f docker-compose.local.yml down
docker-compose -f docker-compose.local.yml build --no-cache
docker-compose -f docker-compose.local.yml up -d

生产环境建议

1. 安全设置

   • 修改默认数据库密码
   • 配置防火墙规则
   • 使用HTTPS

2. 监控和日志

   • 配置日志轮转
   • 设置监控告警
   • 定期备份数据

3. 性能调优

   • 根据负载调整资源配置
   • 配置负载均衡
   • 优化数据库设置

支持

如有问题，请检查：

1. 日志文件
2. 容器状态
3. 网络连接
4. 资源使用情况

🏭 生产环境专用配置

⚠️ 重要安全警告

当前的 docker-compose.yml 和 docker-compose.local.yml 使用默认密码，绝对不能用于生产环境！

生产环境专用文件

• docker-compose.prod.yml - 生产环境Docker配置
• env.prod.example - 生产环境变量模板
• deploy-prod.sh - 自动化生产部署脚本
• nginx-example.conf - Nginx反向代理配置
• mysql-init/ - MySQL安全初始化脚本

生产环境部署步骤

# 1. 复制并配置环境变量
cp env.prod.example .env.prod
nano .env.prod  # 必须修改所有密码！

# 2. 自动化部署（推荐）
./deploy-prod.sh

# 或手动部署
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d --build

生产环境安全特性

• ✅ 强密码要求（环境变量配置）
• ✅ 网络隔离（数据库不对外暴露）
• ✅ 健康检查和自动重启
• ✅ MySQL权限最小化
• ✅ Redis密码保护
• ✅ 会话密钥安全配置
• ✅ 性能优化配置

必须配置的环境变量

MYSQL_ROOT_PASSWORD=strong_password_12+_chars
MYSQL_PASSWORD=strong_password_12+_chars  
REDIS_PASSWORD=strong_password_12+_chars
SESSION_SECRET=random_string_32+_chars

生产环境安全检查清单

• 修改所有默认密码
• 设置强密码（12位以上）
• 配置SESSION_SECRET（32位以上）
• 配置防火墙规则
• 设置SSL证书（参考nginx-example.conf）
• 配置反向代理
• 设置定期备份
• 监控服务健康状态
• 定期更新Docker镜像