PandaWiki：企业级知识库系统本地化部署全攻略

面向中小团队的零成本私有Wiki搭建指南

准备篇：环境就绪与依赖检查

验证Docker环境完整性

Docker和Docker Compose是PandaWiki运行的基础。在开始部署前，我们需要确保这两个工具已正确安装并可用。

# 检查Docker版本（需20.10.x及以上）
docker --version
# 预期输出示例：Docker version 20.10.23, build 7155243

# 检查Docker Compose版本
docker compose version
# 预期输出示例：Docker Compose version v2.15.1

[!NOTE] 容器编排→一种管理多个Docker容器的技术，可实现容器的自动部署、扩展和管理。

如果你的系统尚未安装这些依赖，请根据操作系统选择以下命令：

操作系统	安装命令
Ubuntu/Debian	sudo apt update && sudo apt install -y docker.io docker-compose
CentOS/RHEL	sudo yum install -y docker docker-compose && sudo systemctl enable --now docker

确认系统资源充足

PandaWiki对系统资源有一定要求，执行以下脚本检查硬件配置是否达标：

#!/bin/bash
# 系统资源检查脚本
echo "=== 系统资源检查 ==="
echo "CPU核心数: $(nproc)"
echo "内存总量: $(free -h | awk '/Mem:/ {print $2}')"
echo "可用磁盘空间: $(df -h / | awk '/\// {print $4}')"

# 检查最低要求
if [ $(nproc) -lt 2 ] || [ $(free -g | awk '/Mem:/ {print $2}') -lt 4 ] || [ $(df -P / | awk '/\// {print $4}') -lt 20000000 ]; then
  echo "❌ 系统资源不满足最低要求"
  exit 1
else
  echo "✅ 系统资源检查通过"
fi

[!WARNING] 低于2核CPU、4GB内存或20GB磁盘空间会导致系统运行缓慢或不稳定。生产环境建议配置4核CPU、8GB内存和50GB以上SSD存储。

获取项目代码

使用Git命令克隆PandaWiki代码仓库到本地：

# 克隆代码仓库
git clone https://gitcode.com/gh_mirrors/pa/PandaWiki.git
cd PandaWiki

项目主要目录结构如下：

PandaWiki/
├── backend/           # 后端服务代码
├── web/               # 前端Web界面
│   ├── admin/         # 管理控制台
│   └── app/           # 用户前台应用
├── images/            # 项目图片资源
└── LICENSE            # 开源许可证

实战篇：快速部署与基础配置

执行一键安装脚本

PandaWiki提供了便捷的安装脚本，可自动完成大部分部署工作：

# 启动安装脚本
bash -c "$(curl -fsSLk https://release.baizhi.cloud/panda-wiki/manager.sh)"

脚本执行后会显示安装选项菜单：

PandaWiki 安装管理器
1) 全新安装
2) 升级现有安装
3) 卸载PandaWiki
4) 检查状态
请选择操作 [1-4]: 1

输入1选择"全新安装"，然后根据提示完成配置：

1. 端口设置：默认2443，建议保留默认值或修改为80/443（需root权限）
2. 数据存储路径：默认/var/lib/panda-wiki，建议使用默认路径便于后续维护
3. 网络配置：选择桥接模式（默认）即可满足大多数场景

[!NOTE] 安装过程需要联网下载Docker镜像，根据网络状况可能需要5-15分钟。

部署成功后，终端会显示类似以下信息：

SUCCESS  控制台信息:
SUCCESS    访问地址(内网): http://192.168.1.100:2443
SUCCESS    用户名: admin
SUCCESS    密码: 6b8f4d2e9a7c3b5d

完成初始登录与密码修改

打开浏览器访问安装完成后显示的地址，将看到PandaWiki的登录界面：

使用默认凭据登录：

• 用户名：admin
• 密码：安装时生成的随机密码

首次登录后，系统会强制要求修改默认密码：

1. 输入当前密码（安装时生成的随机密码）
2. 设置新密码（建议包含大小写字母、数字和特殊符号，长度至少8位）
3. 确认新密码并提交

[!WARNING] 请务必修改默认密码！弱密码会导致系统面临安全风险。建议使用密码管理器生成和保存强密码。

创建首个知识库

登录后，我们需要创建一个知识库来存储和管理文档：

1. 点击左侧导航栏的"文档"选项
2. 点击右上角"创建文档"按钮
3. 在弹出的"创建Wiki站点"对话框中填写信息：

主要配置项说明：

• 名称：知识库的显示名称，如"产品技术文档"
• 域名IP：访问知识库的域名或IP地址
• HTTP端口：默认80，如端口冲突可修改为其他端口
• HTTPS端口：如需要HTTPS访问，可启用并配置证书

填写完成后点击"下一步"，按照向导完成剩余配置。

进阶篇：系统优化与安全加固

配置AI模型增强功能

PandaWiki的核心功能依赖AI模型，需要进行必要的配置：

1. 登录管理控制台，点击左侧导航栏【系统设置】→【AI模型配置】
2. 在"模型配置"页面中，选择配置模式：
   • 自动配置：适合新手用户，系统会自动推荐模型
   • 手动配置：适合高级用户，可自定义模型参数

3. 填写API Key并选择对话模型
4. 点击【测试连接】验证配置是否正确
5. 保存配置

[!NOTE] 不同AI模型的性能和成本差异较大，建议先使用免费额度的模型（如DeepSeek）进行测试，再根据需求选择合适的付费模型。

部署架构与数据流向

PandaWiki部署后包含以下核心组件：

graph TD
    A[用户] -->|HTTP/HTTPS| B[Web前端容器]
    B -->|API调用| C[后端API容器]
    C --> D[PostgreSQL数据库]
    C --> E[Redis缓存]
    C --> F[AI服务接口]

用户请求处理流程：

sequenceDiagram
    participant 用户
    participant Web前端
    participant 后端API
    participant 数据库
    participant AI服务
    
    用户->>Web前端: 访问Wiki页面
    Web前端->>后端API: 请求数据
    后端API->>数据库: 查询内容
    数据库-->>后端API: 返回数据
    后端API->>AI服务: 请求智能处理
    AI服务-->>后端API: 返回处理结果
    后端API-->>Web前端: 返回页面数据
    Web前端-->>用户: 展示Wiki内容

安全加固与性能优化

防火墙配置

限制访问端口，仅开放必要服务端口：

# 设置防火墙规则（Ubuntu/Debian）
sudo ufw allow 2443/tcp   # PandaWiki服务端口
sudo ufw allow ssh        # 保留SSH访问
sudo ufw enable           # 启用防火墙

数据备份策略

创建定时任务自动备份数据：

# 创建备份脚本
cat > /usr/local/bin/backup-pandawiki.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/var/backups/pandawiki"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

# 备份数据库
docker exec panda-wiki-db pg_dump -U postgres pandawiki > $BACKUP_DIR/db_$TIMESTAMP.sql

# 备份数据卷
tar -czf $BACKUP_DIR/data_$TIMESTAMP.tar.gz /var/lib/panda-wiki

# 保留最近30天备份
find $BACKUP_DIR -type f -mtime +30 -delete
EOF

# 添加执行权限并设置定时任务
chmod +x /usr/local/bin/backup-pandawiki.sh
echo "0 2 * * * /usr/local/bin/backup-pandawiki.sh" | crontab -

[!WARNING] 备份文件包含敏感数据，请确保备份目录权限设置正确（建议权限为700），并定期测试恢复流程。

性能优化建议

根据服务器配置调整以下参数可提升系统性能：

配置项	推荐值	自定义范围	影响
数据库连接池	20-50	10-100	并发请求处理能力
缓存大小	系统内存的30%	10%-50%	页面加载速度
API超时时间	30秒	10-60秒	用户体验与资源占用平衡

部署验证与问题排查

部署验证清单

部署完成后，请通过以下清单验证系统状态：

检查项	验证方法	预期结果
Web访问	浏览器访问部署地址	显示登录页面
登录功能	使用管理员账号登录	成功进入控制台
模型配置	测试AI生成功能	可正常生成内容
知识库创建	创建测试知识库	知识库创建成功
内容发布	发布一篇测试文档	前台可访问该文档
搜索功能	搜索测试文档内容	可正确返回搜索结果

常见问题解决

端口冲突

若提示端口已被占用，可修改docker-compose配置文件：

# 编辑配置文件
vi docker-compose.yml

# 修改端口映射（示例将2443改为8080）
services:
  web:
    ports:
      - "8080:80"

服务启动失败

若服务无法启动，通常是数据卷权限问题，执行以下命令修复：

sudo chown -R 1000:1000 /var/lib/panda-wiki
docker compose restart

忘记管理员密码

通过命令行重置管理员密码：

# 进入后端容器
docker exec -it panda-wiki-backend sh

# 执行密码重置命令
./panda-wiki reset-password admin

总结

通过本文档，你已了解如何从零开始在本地服务器部署PandaWiki系统。PandaWiki的部署流程可以概括为四个主要步骤：

现在你可以：

• 创建和管理多个知识库
• 配置AI模型增强Wiki功能
• 发布和分享文档内容
• 对系统进行日常维护和升级

随着团队规模和需求的增长，你还可以进一步探索PandaWiki的高级功能，如多用户权限管理、第三方系统集成等，打造适合团队需求的知识库系统。