6.8 KiB
6.8 KiB
NEX Docus Docker 部署文档
完整的 Docker 容器化部署方案，支持一键部署、升级、备份等功能。
🚀 快速开始
1. 环境要求
- Docker 20.10+
- Docker Compose 2.0+
- 至少 2GB 可用内存
- 至少 10GB 可用磁盘空间
2. 首次部署
# 1. 克隆项目（如果还没有）
git clone <your-repo-url>
cd "NEX Docus"
# 2. 配置环境变量
cp .env.example .env
vim .env # 编辑配置文件
# 3. 初始化并启动
./deploy.sh init
3. 配置说明
编辑 .env 文件，修改以下关键配置：
# 数据库配置
DB_NAME=nex_docus
DB_USER=nexdocus
DB_PASSWORD=your_secure_password_here
# Redis 配置
REDIS_PASSWORD=your_redis_password_here
# JWT 密钥（必须修改！）
SECRET_KEY=your-secret-key-change-me-in-production
# 服务端口配置
FRONTEND_PORT=8080 # 前端访问端口
BACKEND_PORT=8000 # 后端 API 端口
# 存储路径配置（用于存储项目文档和上传文件）
STORAGE_PATH=./storage # 可修改为绝对路径，如 /data/nex-docus-storage
# 管理员账号
ADMIN_USERNAME=admin
ADMIN_PASSWORD=Your_Secure_Password_123
ADMIN_EMAIL=admin@yourdomain.com
# API 地址配置
# 推荐：使用 Nginx 反向代理（前后端同域名同端口，无跨域问题）
VITE_API_BASE_URL=/api
# 或：直接访问后端端口（需开放后端端口到外网）
# VITE_API_BASE_URL=http://yourdomain.com:8001
⚠️ 重要提示：
SECRET_KEY必须修改为随机字符串（可用openssl rand -hex 32生成）- 生产环境必须修改所有默认密码
DEBUG设置为falseSTORAGE_PATH可配置为绝对路径，便于数据管理和备份- API 访问配置：
- 使用
VITE_API_BASE_URL=/api时，前端通过 Nginx 反向代理访问后端，无需开放后端端口 - 使用
VITE_API_BASE_URL=http://IP:8001时，直接访问后端，需要开放 8001 端口
- 使用
📋 部署脚本使用
基本命令
# 查看帮助
./deploy.sh help
# 初始化部署（首次部署）
./deploy.sh init
# 启动服务
./deploy.sh start
# 停止服务
./deploy.sh stop
# 重启服务
./deploy.sh restart
# 查看服务状态
./deploy.sh status
日志管理
# 查看所有服务日志
./deploy.sh logs
# 查看后端日志
./deploy.sh logs backend
# 查看前端日志
./deploy.sh logs frontend
# 查看数据库日志
./deploy.sh logs mysql
# 查看 Redis 日志
./deploy.sh logs redis
升级部署
# 升级到最新版本
./deploy.sh upgrade
升级流程：
- 拉取最新代码
- 停止服务
- 构建新镜像
- 更新数据库
- 启动服务
- 清理旧镜像
数据库管理
# 备份数据库
./deploy.sh backup
# 恢复数据库
./deploy.sh restore ./backups/nex_docus_20240101_120000.sql
卸载
# 完全卸载（删除所有容器、镜像和数据）
./deploy.sh uninstall
🏗️ 架构说明
服务组成
| 服务 | 端口 | 说明 |
|---|---|---|
| frontend | 8080 | 前端 Nginx 服务 |
| backend | 8000 | 后端 FastAPI 服务 |
| mysql | 3306 | MySQL 8.0 数据库 |
| redis | 6379 | Redis 缓存 |
目录结构
NEX Docus/
├── backend/ # 后端代码
│ ├── app/ # 应用代码
│ ├── scripts/ # 脚本文件
│ │ └── init_db.py # 数据库初始化
│ ├── Dockerfile # 后端镜像
│ └── requirements.txt # Python 依赖
├── forntend/ # 前端代码
│ ├── src/ # 源代码
│ ├── Dockerfile # 前端镜像
│ └── nginx.conf # Nginx 配置
├── docker-compose.yml # Docker 编排文件
├── .env.example # 环境变量示例
├── deploy.sh # 部署管理脚本
└── DEPLOY.md # 部署文档
数据持久化
所有重要数据都已持久化存储：
mysql_data: MySQL 数据（Docker Volume）redis_data: Redis 数据（Docker Volume）${STORAGE_PATH}: 用户上传的文件和项目文档（宿主机目录映射）- 默认路径:
./storage - 可在
.env中配置STORAGE_PATH修改为其他路径 - 建议使用绝对路径，便于备份和迁移
- 默认路径:
存储目录说明：
- 该目录存储所有项目文档和上传的文件
- 支持独立备份和迁移
- 可配置到独立磁盘或网络存储
🔧 常见问题
1. 端口被占用
如果默认端口被占用，可以在 .env 中修改：
FRONTEND_PORT=8080
BACKEND_PORT=8001
MYSQL_PORT=3307
REDIS_PORT=6380
2. 数据库连接失败
检查 MySQL 容器状态：
docker logs nex-docus-mysql
确保数据库完全启动（约需 10-15 秒）
3. 前端无法访问后端 API
检查 .env 中的 VITE_API_BASE_URL 配置，确保与实际部署地址匹配。
4. 内存不足
如果服务器内存小于 2GB，可能导致 MySQL 无法启动。建议：
- 增加服务器内存
- 或使用外部 MySQL 服务
5. 镜像下载缓慢
已配置国内镜像加速：
- Docker 基础镜像使用华为云镜像
- Debian APT 包使用阿里云镜像源
- Python 使用清华源
- Node 使用淘宝镜像
Docker 镜像源配置（如需更换）：
编辑 /etc/docker/daemon.json：
{
"registry-mirrors": [
"https://mirror.ccs.tencentyun.com",
"https://docker.mirrors.ustc.edu.cn"
]
}
说明：
backend/Dockerfile已配置阿里云 Debian APT 源，系统依赖安装速度大幅提升- 如构建仍然缓慢，可尝试清华源：
mirrors.tuna.tsinghua.edu.cn
🔐 安全建议
-
修改默认密码
- 管理员账号密码
- 数据库密码
- Redis 密码
- JWT 密钥
-
配置防火墙
# 只开放必要端口 ufw allow 80/tcp ufw allow 443/tcp ufw enable -
使用 HTTPS
- 建议配置 Nginx 反向代理
- 使用 Let's Encrypt 免费证书
-
定期备份
# 添加定时任务 crontab -e # 每天凌晨 2 点备份 0 2 * * * cd /path/to/nex-docus && ./deploy.sh backup -
关闭调试模式
DEBUG=false
📊 监控与维护
查看资源使用情况
# Docker 容器资源使用
docker stats
# 磁盘使用情况
df -h
# 清理 Docker 缓存
docker system prune -a
定期维护
# 每周检查日志大小
du -sh backend/logs
# 清理旧日志
find backend/logs -name "*.log" -mtime +30 -delete
🆘 技术支持
如遇问题，请检查：
- 服务日志:
./deploy.sh logs <服务名> - Docker 状态:
docker ps -a - 系统资源:
top或htop
📝 更新日志
v1.0.0 (2024-12-20)
- ✨ 完整的 Docker 部署方案
- ✨ 一键初始化和升级
- ✨ 数据库备份恢复
- ✨ 国内镜像加速
- ✨ 完善的文档和脚本
祝部署顺利！ 🎉