PandaWiki部署全攻略：从环境到运维的实战指南

📋 环境准备

确认系统需求

部署PandaWiki前，请确保服务器满足以下条件：

项目	最低配置	推荐配置
操作系统	Linux (Ubuntu 20.04+/CentOS 8+)	Ubuntu 22.04 LTS
Docker版本	20.10.x	24.0.0+
CPU	2核	4核
内存	4GB RAM	8GB RAM
硬盘	20GB可用空间	50GB SSD
网络	可访问互联网	稳定宽带连接

安装依赖组件

运行以下命令检查Docker和Docker Compose是否已安装：

docker --version
docker compose version

若未安装，根据系统类型执行安装命令：

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

验证环境配置

完成依赖安装后，执行以下命令验证Docker服务状态：

sudo systemctl status docker

预期结果：服务状态显示"active (running)"。

⚠️ 注意事项：

• 确保当前用户拥有Docker执行权限，或使用sudo运行相关命令
• 防火墙需开放部署端口（默认2443），否则可能导致访问失败

📌 模块小结：

• 环境准备是部署的基础，需确保系统配置满足最低要求
• Docker及Docker Compose是部署的核心依赖，必须正确安装并运行
• 环境验证步骤不可省略，可提前发现并解决潜在问题

🚀 部署实施

获取项目代码

运行以下命令克隆PandaWiki代码仓库：

git clone https://gitcode.com/gh_mirrors/pa/PandaWiki.git
cd PandaWiki

项目主要目录结构说明：

• backend/：后端服务代码
• web/：前端Web界面（包含admin管理控制台和app用户前台）
• images/：项目图片资源

执行部署脚本

PandaWiki提供一键安装脚本，运行以下命令启动部署流程：

bash -c "$(curl -fsSLk https://release.baizhi.cloud/panda-wiki/manager.sh)"

在安装菜单中选择"1) 全新安装"，按提示完成配置：

1. 端口设置：默认2443，可根据需求修改
2. 数据存储路径：推荐使用默认路径/var/lib/panda-wiki
3. 网络配置：默认选择桥接模式

验证部署结果

部署完成后，终端将显示访问信息。打开浏览器访问提供的内网地址，应能看到PandaWiki登录界面：

登录信息：

• 用户名：admin
• 密码：部署完成时显示的随机密码

⚠️ 注意事项：

• 部署过程需要联网拉取镜像，确保服务器网络通畅
• 若部署失败，可查看/var/log/panda-wiki/目录下的日志文件排查问题

📌 模块小结：

• 通过官方脚本可简化部署流程，适合大多数用户
• 部署过程中需正确配置端口和存储路径等关键参数
• 部署完成后务必验证访问是否正常，确保基础服务运行良好

⚙️ 系统配置

完成初始设置

首次登录系统后，按以下步骤完成初始化：

1. 修改默认密码：

   • 输入系统提供的随机密码
   • 设置包含大小写字母、数字和特殊符号的强密码
   • 确认新密码并提交

2. 配置系统基础信息：

   • 进入【系统设置】→【基本配置】
   • 设置站点名称、Logo和描述信息
   • 配置邮件服务（用于通知和找回密码）

创建知识库

在管理控制台中创建第一个知识库：

1. 点击左侧导航栏【文档】→【创建文档】
2. 在弹出的创建窗口中填写知识库名称
3. 配置服务监听方式（默认域名和端口）
4. 点击"下一步"完成创建

配置AI模型

PandaWiki核心功能依赖AI模型，需进行如下配置：

1. 进入【系统设置】→【AI模型配置】
2. 选择模型类型（如百智云、DeepSeek等）
3. 输入API密钥和相关参数
4. 点击【测试连接】验证配置有效性
5. 保存配置并应用

⚠️ 注意事项：

• 初始密码修改是安全的必要步骤，请勿跳过
• AI模型配置直接影响系统核心功能，确保API密钥正确且有足够权限
• 大型知识库建议先进行模型测试，确保性能满足需求

📌 模块小结：

• 系统初始化重点在于安全设置和基础配置
• 知识库是PandaWiki的核心组织单元，需合理规划结构
• AI模型配置是实现智能功能的关键，需确保连接正常

🔧 运维管理

服务状态监控

使用以下方法检查PandaWiki服务状态：

1. 通过安装脚本查看：

bash -c "$(curl -fsSLk https://release.baizhi.cloud/panda-wiki/manager.sh)"

选择菜单选项"4) 检查状态"，正常运行时所有服务应显示"运行中"。

2. 使用Docker命令管理：

# 进入项目目录
cd PandaWiki

# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 重启服务
docker compose restart

日志查看与问题排查

当系统出现异常时，可通过以下命令查看服务日志：

# 查看后端API日志
docker compose logs -f backend

# 查看前端Web日志
docker compose logs -f web

常见问题及解决方法：

1. 端口冲突：

   • 编辑docker-compose.yml文件
   • 修改端口映射（如将2443改为其他未占用端口）
   • 重启服务使配置生效

2. 服务启动失败：

   • 检查数据卷权限：

   sudo chown -R 1000:1000 /var/lib/panda-wiki
   

   • 重启服务

数据备份策略

设置定期备份以保障数据安全：

1. 创建备份脚本：

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

2. 添加执行权限并设置定时任务：

chmod +x /usr/local/bin/backup-pandawiki.sh
echo "0 2 * * * /usr/local/bin/backup-pandawiki.sh" | crontab -

⚠️ 注意事项：

• 定期检查备份文件是否生成，确保备份功能正常
• 日志文件可能会占用大量磁盘空间，建议设置日志轮转策略
• 生产环境建议将备份文件存储到异地或云存储

📌 模块小结：

• 定期监控服务状态可及时发现并解决问题
• 熟悉日志查看方法是排查故障的基础技能
• 数据备份是保障系统安全的重要措施，需认真配置

📚 进阶指南

性能优化配置

提升PandaWiki系统性能的关键设置：

1. 资源分配优化：

   • 编辑docker-compose.yml文件
   • 根据服务器配置调整各服务的CPU和内存限制
   • 示例配置：

   services:
     backend:
       deploy:
         resources:
           limits:
             cpus: '2'
             memory: 4G
   

2. 缓存配置：

   • 进入【系统设置】→【性能配置】
   • 调整页面缓存时间和API请求缓存策略
   • 启用Redis缓存以提高数据访问速度

安全加固措施

增强系统安全性的三个关键技巧：

1. 防火墙配置：

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

2. HTTPS配置：

   • 准备SSL证书文件
   • 在管理控制台【系统设置】→【安全配置】中启用HTTPS
   • 上传证书文件并设置HTTPS端口

3. 访问控制：

   • 创建不同权限的用户角色
   • 对敏感操作设置二次验证
   • 定期审计用户操作日志

版本升级方法

保持系统更新的正确流程：

1. 使用官方脚本升级：

bash -c "$(curl -fsSLk https://release.baizhi.cloud/panda-wiki/manager.sh)"

选择菜单选项"2) 升级现有安装"。

2. 手动升级步骤：

# 进入项目目录
cd PandaWiki

# 拉取最新代码
git pull origin main

# 重新构建并启动服务
docker compose down
docker compose up -d --build

⚠️ 注意事项：

• 升级前请务必备份数据，防止版本变更导致的数据问题
• 性能优化需根据实际使用情况调整，并非配置越高越好
• 生产环境建议先在测试环境验证升级包，再应用到正式环境

📌 模块小结：

• 性能优化应根据实际需求和服务器资源进行合理配置
• 安全加固是一个持续过程，需定期更新安全策略
• 系统升级需遵循标准流程，确保数据安全和服务连续性

部署决策流程图

PandaWiki提供多种部署方案，可根据实际需求选择：

1. 快速部署：适合个人用户或测试环境，使用官方一键安装脚本
2. 自定义部署：适合企业环境，可修改配置文件定制端口、存储等参数
3. 集群部署：适合高并发场景，需额外配置负载均衡和数据库集群

选择部署方案时需考虑：

• 预期用户规模和访问量
• 现有IT基础设施
• 运维团队技术能力
• 数据安全和可用性要求

通过合理选择部署方案并遵循本指南的步骤，您可以快速搭建一个功能完善、安全可靠的PandaWiki系统，为团队提供高效的知识库管理和协作平台。