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

一、准备工作：零基础环境搭建指南

1.1 系统环境要求

在开始部署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
网络	可访问互联网	稳定网络连接

1.2 依赖检查与安装

首先检查系统是否已安装Docker和Docker Compose：

# 检查Docker版本
docker --version

# 检查Docker Compose版本
docker compose version

如果尚未安装，根据您的操作系统执行以下命令：

# Ubuntu/Debian系统
sudo apt update && sudo apt install -y docker.io docker-compose
sudo systemctl enable --now docker

# CentOS/RHEL系统
sudo yum install -y docker docker-compose
sudo systemctl enable --now docker

⚠️ 注意：安装完成后，请确保当前用户有Docker操作权限，或使用sudo执行后续命令。

1.3 获取项目代码

使用以下命令克隆PandaWiki项目代码到本地：

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

项目主要目录结构说明：

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

二、核心部署：30分钟快速启动指南

2.1 一键安装流程

PandaWiki提供了便捷的安装脚本，只需执行以下命令即可启动部署流程：

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

执行后会显示安装选项菜单，选择"1) 全新安装"开始部署：

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

2.2 配置选项说明

安装过程中需要完成以下关键配置：

1. 端口设置：默认使用2443端口，如需修改请输入自定义端口号
2. 数据存储路径：建议使用默认路径/var/lib/panda-wiki
3. 网络配置：保持默认桥接模式即可满足大多数使用场景

2.3 部署完成验证

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

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

请记录下访问地址和初始管理员凭据，后续配置会用到。

PandaWiki安装流程：从安装到创建Wiki网站的四个步骤

三、系统配置：避坑式配置流程

3.1 首次登录系统

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

PandaWiki登录界面，输入管理员账号和密码

使用默认凭据登录：

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

3.2 安全设置：修改初始密码

首次登录后，系统会引导您修改默认密码：

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

3.3 创建知识库

成功登录后，首先需要创建知识库：

1. 点击左侧导航栏的"文档"选项
2. 点击右上角"创建文档"按钮
3. 在弹出的对话框中填写知识库名称
4. 配置服务监听方式（默认设置即可）
5. 点击"下一步"完成创建

PandaWiki创建知识库界面，可设置名称和监听端口

3.4 AI模型配置

PandaWiki的核心功能依赖AI模型，需要完成以下配置：

1. 点击右上角"系统配置"按钮
2. 在左侧选项卡中选择"模型配置"
3. 选择"自动配置"或"手动配置"（新手推荐自动配置）
4. 填写API Key（可通过界面提示获取）
5. 选择合适的对话模型（如deepseek-chat）
6. 点击"应用"保存配置

AI模型基础配置界面，可输入API Key和选择对话模型

对于高级用户，可以切换到"手动配置"，详细设置各类模型参数：

AI模型高级配置界面，可分别设置各类模型参数

四、运维管理：日常维护实用指南

4.1 服务状态管理

使用安装脚本可以快速检查服务运行状态：

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

选择菜单选项4查看状态，正常运行时将显示所有服务组件的运行状态。

也可以使用Docker Compose命令直接管理服务：

# 进入项目目录
cd PandaWiki

# 启动服务
docker compose up -d

# 停止服务
docker compose down

# 重启服务
docker compose restart

4.2 日志查看与问题排查

当系统出现问题时，查看日志是排查问题的重要手段：

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

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

4.3 故障排除决策树

遇到问题时，可以按照以下决策树进行排查：

flowchart TD
    A[问题现象] --> B{服务是否运行?}
    B -->|否| C[检查Docker服务状态]
    B -->|是| D{能否访问Web界面?}
    D -->|否| E[检查端口占用情况]
    D -->|是| F{登录是否正常?}
    F -->|否| G[重置管理员密码]
    F -->|是| H{功能是否正常?}
    H -->|否| I[查看应用日志]
    H -->|是| J[检查AI模型配置]

五、进阶优化：系统安全与性能提升

5.1 新手友好型安全清单

为保障系统安全，建议完成以下安全配置：

1. 防火墙设置：

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

2. 定期备份数据： 创建备份脚本并设置定时任务：

   # 创建备份脚本
   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 -
   

5.2 系统性能优化建议

对于使用量较大的场景，可以通过以下方式优化性能：

1. 资源调整：根据实际使用情况调整Docker资源限制
2. 缓存优化：增加Redis缓存容量提升响应速度
3. 数据库优化：定期维护PostgreSQL数据库

5.3 版本升级方法

保持系统为最新版本可以获得新功能和安全更新：

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

选择菜单选项2进行升级，脚本将自动完成更新过程。

六、使用场景与进阶学习

6.1 核心功能使用场景

PandaWiki适用于多种企业知识管理场景：

1. 团队知识库：集中管理项目文档、API手册和技术规范，支持多人协作编辑
2. 客户支持系统：构建产品FAQ和帮助中心，结合AI实现智能问答
3. 内部培训平台：创建结构化培训材料，支持员工自主学习和考核

6.2 进阶学习路径

想要深入了解和使用PandaWiki，可以参考以下学习路径：

1. API开发：探索backend/api目录下的接口定义，开发自定义集成功能
2. 前端定制：修改web目录下的前端代码，定制符合企业风格的界面

6.3 官方资源

• 项目文档：查看项目内的docs目录获取详细开发文档
• 更新日志：关注项目发布版本了解新功能和改进
• 社区支持：通过项目issue系统获取技术支持和交流经验

通过以上步骤，您已经成功部署并配置了PandaWiki企业级知识库系统。随着使用深入，您可以根据实际需求进一步探索系统的高级功能和定制选项。