nex_docus/DEPLOY.md

# NEX Docus Docker 部署文档

完整的 Docker 容器化部署方案，支持一键部署、升级、备份等功能。

## 🚀 快速开始

### 1. 环境要求

- Docker 20.10+
- Docker Compose 2.0+
- 至少 2GB 可用内存
- 至少 10GB 可用磁盘空间

### 2. 首次部署

```bash
# 1. 克隆项目（如果还没有）
git clone <your-repo-url>
cd "NEX Docus"

# 2. 配置环境变量
cp .env.example .env
vim .env  # 编辑配置文件

# 3. 初始化并启动
./deploy.sh init
```

### 3. 配置说明

编辑 `.env` 文件，修改以下关键配置：

```bash
# 数据库配置
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 地址（根据实际域名修改）
VITE_API_BASE_URL=http://yourdomain.com:8000
```

**⚠️ 重要提示：**
- `SECRET_KEY` 必须修改为随机字符串（可用 `openssl rand -hex 32` 生成）
- 生产环境必须修改所有默认密码
- `DEBUG` 设置为 `false`
- `STORAGE_PATH` 可配置为绝对路径，便于数据管理和备份

## 📋 部署脚本使用

### 基本命令

```bash
# 查看帮助
./deploy.sh help

# 初始化部署（首次部署）
./deploy.sh init

# 启动服务
./deploy.sh start

# 停止服务
./deploy.sh stop

# 重启服务
./deploy.sh restart

# 查看服务状态
./deploy.sh status
```

### 日志管理

```bash
# 查看所有服务日志
./deploy.sh logs

# 查看后端日志
./deploy.sh logs backend

# 查看前端日志
./deploy.sh logs frontend

# 查看数据库日志
./deploy.sh logs mysql

# 查看 Redis 日志
./deploy.sh logs redis
```

### 升级部署

```bash
# 升级到最新版本
./deploy.sh upgrade
```

升级流程：
1. 拉取最新代码
2. 停止服务
3. 构建新镜像
4. 更新数据库
5. 启动服务
6. 清理旧镜像

### 数据库管理

```bash
# 备份数据库
./deploy.sh backup

# 恢复数据库
./deploy.sh restore ./backups/nex_docus_20240101_120000.sql
```

### 卸载

```bash
# 完全卸载（删除所有容器、镜像和数据）
./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` 中修改：

```bash
FRONTEND_PORT=8080
BACKEND_PORT=8001
MYSQL_PORT=3307
REDIS_PORT=6380
```

### 2. 数据库连接失败

检查 MySQL 容器状态：
```bash
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`：
```json
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://docker.mirrors.ustc.edu.cn"
  ]
}
```

**说明**：
- `backend/Dockerfile` 已配置阿里云 Debian APT 源，系统依赖安装速度大幅提升
- 如构建仍然缓慢，可尝试清华源：`mirrors.tuna.tsinghua.edu.cn`

## 🔐 安全建议

1. **修改默认密码**
   - 管理员账号密码
   - 数据库密码
   - Redis 密码
   - JWT 密钥

2. **配置防火墙**
   ```bash
   # 只开放必要端口
   ufw allow 80/tcp
   ufw allow 443/tcp
   ufw enable
   ```

3. **使用 HTTPS**
   - 建议配置 Nginx 反向代理
   - 使用 Let's Encrypt 免费证书

4. **定期备份**
   ```bash
   # 添加定时任务
   crontab -e
   # 每天凌晨 2 点备份
   0 2 * * * cd /path/to/nex-docus && ./deploy.sh backup
   ```

5. **关闭调试模式**
   ```bash
   DEBUG=false
   ```

## 📊 监控与维护

### 查看资源使用情况

```bash
# Docker 容器资源使用
docker stats

# 磁盘使用情况
df -h

# 清理 Docker 缓存
docker system prune -a
```

### 定期维护

```bash
# 每周检查日志大小
du -sh backend/logs

# 清理旧日志
find backend/logs -name "*.log" -mtime +30 -delete
```

## 🆘 技术支持

如遇问题，请检查：

1. 服务日志: `./deploy.sh logs <服务名>`
2. Docker 状态: `docker ps -a`
3. 系统资源: `top` 或 `htop`

## 📝 更新日志

### v1.0.0 (2024-12-20)
- ✨ 完整的 Docker 部署方案
- ✨ 一键初始化和升级
- ✨ 数据库备份恢复
- ✨ 国内镜像加速
- ✨ 完善的文档和脚本

---

**祝部署顺利！** 🎉