生产环境部署
以下示例使用单实例,持久化统计和 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 缓存,可以避免同时写文件;此时统计也会分散在各实例。若需要统一统计、共享缓存或高可用一致性,需先改造存储与同步机制,不能只增加副本数量。
更多问题见 常见问题。