# Docker 部署指南

本文档说明如何使用 Docker 部署 CJYDocs 文档管理系统。

## 快速开始

```bash
# 1. 构建镜像
docker build -t cjydocs:latest .

# 2. 运行容器
docker run -d \
  --name cjydocs \
  -p 3000:3000 \
  -v $(pwd)/docs:/app/docs \
  -v $(pwd)/index.md:/app/index.md \
  --restart unless-stopped \
  cjydocs:latest

# 3. 查看日志
docker logs -f cjydocs

# 4. 停止容器
docker stop cjydocs

# 5. 删除容器
docker rm cjydocs
```

## 镜像说明

### 镜像特性

- **基础镜像**: Node.js 18 Alpine (轻量级)
- **镜像大小**: 约 150MB
- **健康检查**: 自动检测应用状态

### 多阶段构建

Dockerfile 采用多阶段构建优化镜像大小:

1. **构建阶段**: 安装生产依赖
2. **运行阶段**: 只复制必要文件,减小镜像体积

## 卷挂载说明

### 必需挂载

```bash
-v $(pwd)/docs:/app/docs          # 文档存储目录
-v $(pwd)/index.md:/app/index.md  # 文档结构配置
```

### 可选挂载

```bash
# 自定义样式
-v $(pwd)/public/css/style.css:/app/public/css/style.css

# 自定义前端脚本
-v $(pwd)/public/js:/app/public/js
```

## 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `NODE_ENV` | `production` | Node.js 运行环境 |
| `PORT` | `3000` | 应用监听端口 |

## 端口映射

| 容器端口 | 宿主机端口 | 说明 |
|----------|------------|------|
| `3000` | `3000` | HTTP 服务端口 |

可以修改 docker run 命令中的端口映射:

```bash
# 映射到宿主机 8080 端口
docker run -d -p 8080:3000 ...
```

## 数据持久化

### 文档数据

所有文档存储在 `./docs` 目录,通过卷挂载持久化:

```bash
# 宿主机目录结构
docs/
├── 分类1/
│   ├── 文档A.md
│   └── 文档B.md
└── 分类2/
    └── 文档C.md
```

在宿主机修改文档后,容器内立即生效(有5秒缓存)。

### 配置文件

`index.md` 定义文档结构,修改后刷新浏览器即可看到变化。

## 常用操作

### 查看容器状态

```bash
docker ps | grep cjydocs
```

### 进入容器

```bash
docker exec -it cjydocs sh
```

### 查看实时日志

```bash
docker logs -f cjydocs
```

### 更新应用

```bash
# 1. 停止并删除旧容器
docker stop cjydocs
docker rm cjydocs

# 2. 重新构建镜像
docker build --no-cache -t cjydocs:latest .

# 3. 启动新容器
docker run -d \
  --name cjydocs \
  -p 3000:3000 \
  -v $(pwd)/docs:/app/docs \
  -v $(pwd)/index.md:/app/index.md \
  --restart unless-stopped \
  cjydocs:latest
```

### 备份文档

```bash
# 备份整个 docs 目录
tar -czf docs_backup_$(date +%Y%m%d).tar.gz docs/ index.md

# 从容器中导出数据
docker cp cjydocs:/app/docs ./docs_backup/
docker cp cjydocs:/app/index.md ./docs_backup/
```

### 恢复文档

```bash
# 解压备份
tar -xzf docs_backup_20231201.tar.gz

# 重启容器使更改生效
docker restart cjydocs
```

## 资源限制

可以使用 Docker 命令行参数限制容器资源:

```bash
docker run -d \
  --name cjydocs \
  --cpus="1" \              # 最多使用 1 个 CPU 核心
  --memory="512m" \         # 最多使用 512MB 内存
  -p 3000:3000 \
  -v $(pwd)/docs:/app/docs \
  -v $(pwd)/index.md:/app/index.md \
  --restart unless-stopped \
  cjydocs:latest
```

## 健康检查

Dockerfile 中已配置健康检查,每 30 秒自动检查一次应用状态。

查看健康状态:

```bash
docker inspect --format='{{.State.Health.Status}}' cjydocs
```

## 日志管理

可以通过 Docker 命令行参数配置日志:

```bash
docker run -d \
  --name cjydocs \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  -p 3000:3000 \
  -v $(pwd)/docs:/app/docs \
  -v $(pwd)/index.md:/app/index.md \
  --restart unless-stopped \
  cjydocs:latest
```

这样配置后,总日志占用不超过 30MB (10MB × 3 个文件)。

## 网络配置

### 反向代理 (Nginx)

如果使用 Nginx 作为反向代理:

```nginx
server {
    listen 80;
    server_name docs.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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;
    }
}
```

### Docker 网络

如果需要多个容器通信,可以创建自定义网络:

```bash
# 创建网络
docker network create app-network

# 运行容器时连接到网络
docker run -d \
  --name cjydocs \
  --network app-network \
  -p 3000:3000 \
  -v $(pwd)/docs:/app/docs \
  -v $(pwd)/index.md:/app/index.md \
  cjydocs:latest

# 其他容器也连接到同一网络
docker run -d \
  --name nginx \
  --network app-network \
  -p 80:80 \
  nginx:alpine
```

## 故障排查

### 容器无法启动

```bash
# 查看详细日志
docker logs cjydocs

# 检查端口占用
netstat -an | grep 3000
# Windows: netstat -an | findstr 3000

# 检查卷挂载权限
ls -la docs/
```

### 健康检查失败

```bash
# 进入容器手动测试
docker exec -it cjydocs sh
wget -O- http://localhost:3000/api/structure
```

### 文档修改不生效

- 等待 5 秒缓存过期
- 检查文件挂载是否正确: `docker exec cjydocs ls -la /app/docs`
- 重启容器: `docker restart cjydocs`

### 性能问题

- 调整资源限制
- 检查日志是否有错误
- 监控容器资源使用: `docker stats cjydocs`

## 生产环境建议

### 1. 使用环境变量管理配置

通过 Docker 命令行传递环境变量:

```bash
docker run -d \
  --name cjydocs \
  -e NODE_ENV=production \
  -e PORT=3000 \
  -p 3000:3000 \
  -v $(pwd)/docs:/app/docs \
  -v $(pwd)/index.md:/app/index.md \
  --restart unless-stopped \
  cjydocs:latest
```

### 2. 启用 HTTPS

使用 Let's Encrypt + Nginx 反向代理,或使用 Traefik。

### 3. 定期备份

设置定时任务备份 `docs/` 和 `index.md`。

### 4. 监控

- 使用 Prometheus + Grafana 监控容器资源
- 配置日志收集 (ELK/Loki)
- 设置告警规则

### 5. 更新策略

- 测试环境验证新版本
- 使用蓝绿部署或滚动更新
- 保持数据备份

## 安全建议

1. **最小权限原则**: 只暴露必要的端口和挂载必要的卷
2. **定期更新**: 更新基础镜像和依赖包
3. **网络隔离**: 使用 Docker 网络隔离容器
4. **镜像扫描**: 使用 `docker scan` 扫描镜像漏洞

```bash
docker scan cjydocs:latest
```

## 常见问题

### Q: 如何修改端口?

A: 修改 docker run 命令中的端口映射:

```bash
docker run -d -p 8080:3000 ...  # 宿主机使用 8080 端口
```

### Q: 如何添加新文档?

A: 直接在宿主机 `docs/` 目录下添加文件,并更新 `index.md`,无需重启容器。

### Q: 如何查看容器内的文件?

A: 使用 `docker exec`:

```bash
docker exec cjydocs ls -la /app/docs
```

### Q: 容器占用多少资源?

A: 查看实时资源使用:

```bash
docker stats cjydocs
```

## 相关链接

- [Docker 官方文档](https://docs.docker.com/)
- [Node.js Alpine 镜像](https://hub.docker.com/_/node)
- [Dockerfile 最佳实践](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)