生产环境部署

以下示例使用单实例,持久化统计和 Git 缓存,并由 Nginx 提供 HTTPS。应用当前使用本地 JSON 与 Git 工作目录,不应让多个实例同时写入同一目录。

固定应用版本

如需部署 v1.6.2,可以从源码构建;第三方 Docker 镜像的标签和发布时间独立于 GitHub Release,请确认其版本后再使用。

git clone --branch v1.6.2 https://github.com/steven-ld/PowerWiki.git
cd PowerWiki
cp config.example.json config.json
# 编辑 config.json,设置 gitRepo、repoBranch 和 siteUrl
docker build -t powerwiki:v1.6.2 .

持久化与启动

在项目根目录创建 compose.prod.yml:

services:
  powerwiki:
    image: powerwiki:v1.6.2
    ports:
      - "127.0.0.1:3150:3150"
    environment:
      NODE_ENV: production
      CONFIG_PATH: /app/config.json
      DATA_DIR: /app/data
      GIT_CACHE_DIR: /app/cache
    volumes:
      - ./config.json:/app/config.json:ro
      - powerwiki_data:/app/data
      - powerwiki_cache:/app/cache
    restart: unless-stopped
    stop_grace_period: 30s
volumes:
  powerwiki_data:
  powerwiki_cache:
docker compose -f compose.prod.yml up -d
docker compose -f compose.prod.yml logs --tail 100

示例使用默认端口 3150,修改应用端口时需同步调整映射。Git 缓存卷避免每次重建容器都重新克隆。

Nginx 反向代理

以下 server 配置用于宿主机 Nginx,需替换域名和已配置的证书路径。

server {
    listen 80;
    server_name wiki.example.com;
    return 301 https://$host$request_uri;
}
server {
    listen 443 ssl;
    server_name wiki.example.com;
    ssl_certificate /etc/letsencrypt/live/wiki.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wiki.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:3150;
        proxy_set_header Host $host;
        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;
        proxy_cache off;
    }
}

保留应用提供的缓存头。不要为所有请求统一设置一小时缓存,也不要对无版本号的 JS/CSS 强制 immutable;缓存 /api/version 会导致浏览器无法及时发现文档变化。

监测与排查

curl -fsS http://127.0.0.1:3150/api/version
docker compose -f compose.prod.yml logs --tail 100

首页返回成功只能说明 HTTP 服务可达,不代表 Git 同步已经完成。结合日志、版本接口和实际文章确认状态。应用目前不提供专用 /health 或 Prometheus /metrics 接口;如需监控,可使用外部 HTTP 探测与容器指标。

备份与升级

  • 文档以远端 Git 仓库为准,同时备份配置及统计数据卷。
  • 一致性备份应先正常停止应用,等待统计刷新后再备份数据卷。
  • 升级前保留旧镜像和备份,使用新版本标签构建并替换 Compose 镜像。
  • 回滚时恢复旧镜像;恢复统计文件前应停止服务,避免覆盖仍在写入的数据。
  • 使用 docker compose stop 正常停止;强制终止可能丢失最后约 5 秒的统计。

多实例边界

为各实例提供独立的统计目录和 Git 缓存,可以避免同时写文件;此时统计也会分散在各实例。若需要统一统计、共享缓存或高可用一致性,需先改造存储与同步机制,不能只增加副本数量。

更多问题见 常见问题。