Docker 部署指南

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

快速开始

# 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 采用多阶段构建优化镜像大小:

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

卷挂载说明

必需挂载

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

可选挂载

# 自定义样式
-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 命令中的端口映射:

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

数据持久化

文档数据

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

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

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

配置文件

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

常用操作

查看容器状态

docker ps | grep cjydocs

进入容器

docker exec -it cjydocs sh

查看实时日志

docker logs -f cjydocs

更新应用

# 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

备份文档

# 备份整个 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/

恢复文档

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

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

资源限制

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

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 秒自动检查一次应用状态。

查看健康状态:

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

日志管理

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

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 作为反向代理:

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 网络

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

# 创建网络
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

故障排查

容器无法启动

# 查看详细日志
docker logs cjydocs

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

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

健康检查失败

# 进入容器手动测试
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 命令行传递环境变量:

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. 更新策略

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

安全建议

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

常见问题

Q: 如何修改端口?

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

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

Q: 如何添加新文档?

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

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

A: 使用 docker exec:

docker exec cjydocs ls -la /app/docs

Q: 容器占用多少资源?

A: 查看实时资源使用:

docker stats cjydocs

DOCKER.md 7.2 KB History Raw