部署常见问题

2026年2月6日

PowerWiki 部署常见问题

本文档整理了 PowerWiki 部署过程中的常见问题和解决方案。

Docker 部署问题

容器无法启动

问题描述: 运行 docker run 后容器立即退出

解决方案:

查看容器日志

docker logs powerwiki

检查配置文件是否存在

ls -la /path/to/config.json

检查配置文件格式

cat config.json | python -m json.tool

确保端口未被占用

lsof -i :3150

拉取镜像失败

问题描述: docker pull 失败或速度很慢

解决方案:

检查网络连接

ping hub.docker.com

配置 Docker 镜像加速器（中国用户）

# 编辑 /etc/docker/daemon.json
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com"
  ]
}

# 重启 Docker
sudo systemctl restart docker

使用代理

docker pull sayunchuan/powerwiki --proxy http://proxy.example.com:8080

容器运行但无法访问

问题描述: 容器正常运行，但浏览器无法访问

解决方案:

检查容器状态

docker ps | grep powerwiki

检查端口映射

docker port powerwiki

检查防火墙

sudo ufw allow 3150/tcp

测试容器内部服务

docker exec powerwiki curl http://localhost:3150

数据丢失

问题描述: 重启容器后数据丢失

解决方案:

使用数据卷持久化数据：

docker run -d \
  -v powerwiki_data:/app/data \
  -v powerwiki_cache:/app/cache \
  sayunchuan/powerwiki

更新镜像后出错

问题描述: 更新到新版本后无法启动

解决方案:

回滚到旧版本

docker run -d sayunchuan/powerwiki:1.4.5

检查配置文件兼容性

# 对比新旧版本的配置示例
docker run --rm sayunchuan/powerwiki:latest cat /app/config.example.json

清理缓存

docker volume rm powerwiki_cache

配置问题

config.json 格式错误

问题描述: 配置文件格式不正确导致启动失败

解决方案:

验证 JSON 格式

cat config.json | python -m json.tool

检查必填字段

{
  "gitRepo": "必填 - Git 仓库地址",
  "port": 3150
}

使用配置模板

cp config.example.json config.json

Git 仓库无法访问

问题描述: PowerWiki 无法克隆或拉取 Git 仓库

解决方案:

测试仓库连接

git clone <your-repo-url> test-repo

检查仓库 URL 格式

正确: https://github.com/username/repo.git
错误: https://github.com/username/repo

私有仓库需要认证

{
  "gitRepo": "https://username:token@github.com/username/repo.git"
}

使用 SSH（需要配置密钥）

{
  "gitRepo": "git@github.com:username/repo.git"
}

端口冲突

问题描述: 3150 端口已被占用

解决方案:

查看占用端口的进程

lsof -i :3150

使用不同端口

docker run -d -p 8080:3150 sayunchuan/powerwiki

或修改配置文件：

{
  "port": 8080
}

自动同步不工作

问题描述: Git 仓库更新后 PowerWiki 没有自动同步

解决方案:

检查同步间隔配置

{
  "autoSyncInterval": 180000
}

手动触发同步

docker restart powerwiki

查看日志

docker logs -f powerwiki | grep sync

性能问题

启动速度慢

问题描述: PowerWiki 启动需要很长时间

可能原因:

Git 仓库太大
网络连接慢
磁盘 I/O 慢

解决方案:

使用浅克隆

# 在 Git 仓库中设置
git clone --depth 1 <repo-url>

减少仓库大小

# 清理 Git 历史
git gc --aggressive --prune=now

使用 SSD 存储

内存占用高

问题描述: PowerWiki 占用内存过多

解决方案:

限制容器内存

docker run -d -m 512m sayunchuan/powerwiki

清理缓存

docker exec powerwiki rm -rf /app/cache/*

增加同步间隔

{
  "autoSyncInterval": 600000
}

CPU 占用高

问题描述: PowerWiki CPU 使用率过高

解决方案:

限制 CPU 使用

docker run -d --cpus="1.0" sayunchuan/powerwiki

检查是否频繁同步

docker logs powerwiki | grep sync | tail -20

使用反向代理缓存

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=powerwiki_cache:10m;

页面加载慢

问题描述: 访问 PowerWiki 页面加载很慢

解决方案:

启用 Nginx 缓存
压缩静态资源
使用 CDN
优化图片大小

网络问题

无法访问 PowerWiki

问题描述: 浏览器无法打开 PowerWiki

排查步骤:

检查容器状态

docker ps | grep powerwiki

检查端口映射

docker port powerwiki

测试本地访问

curl http://localhost:3150

检查防火墙

sudo ufw status
sudo ufw allow 3150/tcp

检查 DNS 解析（如果使用域名）

nslookup wiki.example.com

HTTPS 证书错误

问题描述: 浏览器提示证书不安全

解决方案:

使用 Let's Encrypt 免费证书

sudo certbot certonly --standalone -d wiki.example.com

配置 Nginx SSL

ssl_certificate /etc/letsencrypt/live/wiki.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/wiki.example.com/privkey.pem;

自动续期

sudo certbot renew --dry-run

跨域问题

问题描述: 前端请求被 CORS 阻止

解决方案:

在 Nginx 中配置 CORS：

add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";

数据问题

如何备份数据

问题描述: 需要备份 PowerWiki 数据

解决方案:

备份数据卷

docker run --rm \
  -v powerwiki_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/data-$(date +%Y%m%d).tar.gz -C /data .

备份配置文件

cp config.json config-$(date +%Y%m%d).json

备份 Git 仓库

git clone --mirror <your-repo-url> backup.git

如何恢复数据

问题描述: 需要从备份恢复数据

解决方案:

恢复数据卷

docker run --rm \
  -v powerwiki_data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/data-20260207.tar.gz -C /data

恢复配置文件

cp config-20260207.json config.json

重启容器

docker restart powerwiki

数据不同步

问题描述: Git 仓库更新了但 PowerWiki 没有显示

解决方案:

手动触发同步

docker restart powerwiki

清理缓存

docker exec powerwiki rm -rf /app/cache/*
docker restart powerwiki

检查 Git 仓库配置

docker exec powerwiki cat /app/config.json

获取帮助

如果以上方案无法解决您的问题，可以通过以下方式获取帮助：

查看文档

提交 Issue

社区讨论

GitHub Discussions

最后更新: 2026-02-07

更新时间：2026年2月24日

PowerWiki 部署常见问题

目录

Docker 部署问题

容器无法启动

拉取镜像失败

容器运行但无法访问

数据丢失

更新镜像后出错

配置问题

config.json 格式错误

Git 仓库无法访问

端口冲突

自动同步不工作

性能问题

启动速度慢

内存占用高

CPU 占用高

页面加载慢

网络问题

无法访问 PowerWiki

HTTPS 证书错误

跨域问题

数据问题

如何备份数据

如何恢复数据

数据不同步

获取帮助

查看文档

提交 Issue

社区讨论