PandaWiki本地服务器部署实战指南：从环境准备到系统优化

1. 3步完成PandaWiki部署环境准备

在开始PandaWiki的部署之旅前，确保你的服务器满足基本运行条件并安装必要工具是至关重要的第一步。这不仅能避免后续部署过程中出现兼容性问题，还能确保系统以最佳状态运行。本章节将引导你完成环境检查、依赖安装和硬件配置评估。

1.1 系统与硬件要求对照

PandaWiki对运行环境有特定要求，以下是最低配置与推荐配置的对比：

配置项	最低配置	推荐配置	说明
操作系统	Linux (Ubuntu 20.04/CentOS 8)	Ubuntu 22.04 LTS	推荐使用长期支持版本以获得更好的稳定性
Docker版本	20.10.x	24.0.0+	确保支持最新容器特性
CPU	2核	4核	AI处理和并发请求需要足够的计算能力
内存	4GB RAM	8GB RAM	内存不足会导致文档处理和搜索功能缓慢
硬盘	20GB可用空间	100GB SSD	SSD可显著提升数据库操作和文件访问速度
网络	基本互联网访问	稳定宽带连接	用于拉取镜像和AI模型交互

1.2 核心依赖安装步骤

PandaWiki基于Docker容器化部署，需要先安装Docker和Docker Compose：

1. 检查现有Docker版本（如已安装）：

   docker --version          # 检查Docker引擎版本
   docker compose version    # 检查Docker Compose版本
   

   预期输出示例：Docker version 24.0.6, build ed223bc

2. 安装Docker环境：

   • 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
     

3. 验证安装结果：

   sudo docker run hello-world  # 运行测试容器
   

   看到"Hello from Docker!"消息表示安装成功

1.3 项目代码获取

获取PandaWiki源代码是部署的基础，通过以下步骤克隆官方仓库：

git clone https://gitcode.com/gh_mirrors/pa/PandaWiki.git
cd PandaWiki  # 进入项目目录

项目主要目录结构说明：

• backend/：后端服务代码，包含API接口和业务逻辑
• web/：前端Web界面，分为管理控制台(admin/)和用户前台(app/)
• images/：项目图片资源，包含界面截图和图标
• docker-compose.yml：容器编排配置文件（后续部署会用到）

2. 5分钟快速部署PandaWiki系统

完成环境准备后，我们进入实际部署阶段。PandaWiki提供了简化的安装流程，通过官方安装脚本可自动完成大部分配置工作。本章节将详细介绍部署步骤、配置选项和验证方法。

2.1 一键部署脚本执行

PandaWiki官方提供了便捷的安装管理器脚本，执行以下命令启动部署流程：

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

风险提示：执行远程脚本前，建议先通过浏览器访问脚本URL查看内容，确保安全性。对于生产环境，可考虑下载脚本后离线执行。

2.2 安装配置向导操作

脚本启动后会显示交互式菜单，选择"全新安装"开始配置：

1. 选择安装类型：

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

   输入1并按回车继续

2. 关键配置项设置：

   • 端口设置：默认使用2443端口。修改前建议使用netstat -tuln | grep 2443检查端口占用情况
   • 数据存储路径：建议使用默认路径/var/lib/panda-wiki（数据卷，用于持久化存储的独立空间）
   • 网络配置：保持默认桥接模式即可满足大多数场景

3. 部署过程监控： 安装脚本将自动完成以下操作：

   • 拉取必要的Docker镜像（后端API、前端Web、数据库等）
   • 创建数据卷并设置权限
   • 配置容器网络和环境变量
   • 启动所有服务组件

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

SUCCESS  控制台信息:
SUCCESS    访问地址(内网): http://192.168.1.100:2443
SUCCESS    用户名: admin
SUCCESS    密码: 6b8f4d2e9a7c3b5d  # 实际部署时会生成随机密码

图1：PandaWiki部署流程示意图，展示从安装到创建Wiki网站的完整步骤

3. 系统初始化与基础配置实战

部署完成后，需要进行必要的初始化配置才能正常使用PandaWiki的全部功能。这包括首次登录、密码修改、AI模型配置和知识库创建等关键步骤。正确的初始化设置将为后续使用奠定良好基础。

3.1 首次登录系统

1. 访问管理控制台： 打开浏览器，输入部署完成后显示的内网地址（如http://192.168.1.100:2443），将看到PandaWiki登录界面。

   图2：PandaWiki管理控制台登录界面

2. 使用默认凭据登录：

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

3. 强制修改初始密码： 首次登录后，系统会自动弹出密码修改窗口：

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

3.2 AI模型配置指南

PandaWiki的核心功能依赖AI模型，必须正确配置才能启用智能问答和内容生成功能：

1. 进入模型配置页面： 登录后点击左侧导航栏【系统设置】→【AI模型配置】

2. 基础模型配置：

   • 选择配置模式："自动配置"适合新手，"手动配置"适合高级用户
   • 输入API Key：根据选择的AI服务提供商（如百智云、DeepSeek等）获取并填写
   • 选择对话模型：从下拉列表中选择适合的模型（如deepseek-chat）

   图3：AI模型基础配置界面

3. 高级模型设置： 切换到"手动配置"可看到更多高级选项：

   • 智能对话模型：主模型，用于生成回答内容
   • 向量模型：用于文档向量化和相似度计算
   • 重排模型：用于优化搜索结果排序
   • 文档分析模型：用于解析和处理上传的文档
   • 图像分析模型（可选）：启用后支持图片内容分析

   图4：AI模型高级配置界面，显示多种模型的状态和设置选项

4. 测试连接： 完成配置后点击【测试连接】按钮，确保所有模型显示"状态正常"

3.3 创建第一个知识库

知识库是PandaWiki存储和组织文档的基本单位，创建步骤如下：

1. 启动创建向导： 点击控制台顶部的【创建文档】按钮，选择"创建Wiki站点"

2. 配置知识库基本信息：

   • 输入名称：如"公司产品文档"
   • 设置域名/IP：通常使用服务器IP或绑定的域名
   • 配置端口：默认HTTP端口80，HTTPS端口443（如需HTTPS需上传证书）

   图5：创建Wiki站点配置界面

3. 完成后续设置： 点击"下一步"完成内容导入、发布设置和页面装饰等步骤，最后点击"完成配置"

4. 运维与优化全攻略

成功部署并初始化PandaWiki后，掌握基本的服务管理、问题排查和性能优化方法对于系统长期稳定运行至关重要。本章节将介绍日常运维任务、常见问题解决和安全加固措施，帮助你高效管理PandaWiki系统。

4.1 日常服务管理

PandaWiki基于Docker Compose管理服务，以下是常用操作命令：

1. 服务状态检查：

   # 通过安装脚本查看状态
   bash -c "$(curl -fsSLk https://release.baizhi.cloud/panda-wiki/manager.sh)"
   # 选择菜单选项4查看状态
   

   正常运行时应显示所有服务"运行中"状态

2. 手动控制服务：

   cd /path/to/PandaWiki  # 进入项目目录
   
   docker compose up -d   # 启动所有服务 (-d表示后台运行模式)
   docker compose down    # 停止所有服务
   docker compose restart # 重启所有服务
   docker compose logs -f backend  # 实时查看后端API日志
   

3. 日志查看与问题排查：

   • 后端API日志：docker compose logs -f backend
   • 前端Web日志：docker compose logs -f web
   • 数据库日志：docker compose logs -f db

4.2 常见问题解决方案

端口冲突问题

当启动服务时提示"Bind for 0.0.0.0:2443 failed"表示端口被占用：

1. 查找占用进程：

   sudo lsof -i :2443  # 查找占用2443端口的进程
   

2. 修改配置文件：

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

   修改web服务的端口映射，例如将2443改为8080：

   services:
     web:
       ports:
         - "8080:80"  # 左侧为宿主机端口，右侧为容器内部端口
   

3. 重启服务使更改生效：

   docker compose down && docker compose up -d
   

服务启动失败

若服务无法启动，常见原因是数据卷权限问题：

# 修复数据卷目录权限
sudo chown -R 1000:1000 /var/lib/panda-wiki
docker compose restart  # 重启服务

忘记管理员密码

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

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

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

系统会提示设置新密码，完成后使用新密码登录

4.3 安全加固方案

根据用户技术水平提供两种安全加固方案：

新手友好型方案

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
   
   # 设置每天凌晨2点自动备份
   echo "0 2 * * * /usr/local/bin/backup-pandawiki.sh" | crontab -
   

进阶型方案

1. 启用HTTPS加密：

   • 在创建知识库时启用HTTPS端口
   • 上传有效的SSL证书文件和私钥
   • 配置自动重定向HTTP到HTTPS

2. 网络隔离与访问控制：

   • 使用Docker网络隔离容器
   • 配置Nginx反向代理并启用Basic Auth
   • 限制数据库仅允许容器内部访问

3. 定期安全更新：

   # 创建更新脚本
   cat > /usr/local/bin/update-pandawiki.sh << 'EOF'
   #!/bin/bash
   cd /path/to/PandaWiki
   
   # 拉取最新代码
   git pull
   
   # 更新Docker镜像
   docker compose pull
   
   # 重启服务
   docker compose down && docker compose up -d
   
   # 清理无用资源
   docker system prune -af
   EOF
   
   chmod +x /usr/local/bin/update-pandawiki.sh
   

5. 部署后必做的3件事

完成PandaWiki部署后，以下三个步骤对于系统安全和高效使用至关重要，建议在正式投入使用前完成：

5.1 系统状态全面检查

使用以下清单验证部署是否成功：

• [ ] 访问Web控制台：能正常显示登录页面
• [ ] 管理员登录：使用修改后的密码成功登录
• [ ] AI模型配置：所有必要模型测试连接成功
• [ ] 知识库创建：成功创建至少一个测试知识库
• [ ] 文档发布：在测试知识库中发布一篇测试文档
• [ ] 搜索功能：能搜索到刚刚发布的测试文档
• [ ] 问答功能：向AI提问能得到合理回答

5.2 安全基础设置

1. 创建普通用户：

   • 进入【用户管理】创建非管理员账号
   • 根据需求分配适当权限
   • 日常操作使用普通用户账号

2. 配置访问策略：

   • 设置IP访问限制（如有需要）
   • 启用操作日志记录
   • 配置会话超时时间

3. 数据保护设置：

   • 确认自动备份任务正常运行
   • 测试备份文件恢复功能
   • 设置关键操作二次验证

5.3 性能优化调整

1. 资源分配优化：

   • 根据服务器配置调整Docker资源限制
   • 优化数据库连接池设置
   • 配置缓存策略提升访问速度

2. 系统参数调优：

   • 根据知识库大小调整搜索索引策略
   • 优化AI模型调用参数
   • 配置CDN加速静态资源（适用于公网访问场景）

通过完成以上步骤，你的PandaWiki系统将处于安全、稳定且高效的运行状态，为团队提供强大的知识库和智能问答功能。随着使用深入，可根据实际需求进一步探索高级功能和定制化配置。