PandaWiki开源版部署操作手册：零基础10分钟搭建智能知识库

AI 百科1周前更新 Timi
0 0 0

对于追求数据自主可控的团队来说，PandaWiki开源版的本地部署是最优解——无需复杂技术背景，依托Docker容器化技术，跟着步骤一步步操作，就能快速拥有属于自己的智能知识库。本文整合实测验证的部署流程、环境配置细节和常见问题排查，全程无晦涩术语，零基础也能轻松上手。

一、部署前准备：确认环境与资源

1. 硬件配置要求

  • 推荐配置：2核CPU + 4GB内存 + 20GB可用磁盘（支持10人以内团队稳定使用）
  • 最低配置：1核CPU + 2GB内存 + 5GB可用磁盘（仅适合个人测试或2-3人临时使用）
  • 存储建议：若需存储大量文档、附件，建议预留50GB以上磁盘空间，避免后期扩容麻烦

2. 软件环境要求

  • 操作系统：Linux内核3.10以上，推荐Ubuntu 20.04+/CentOS 7+（x86_64架构，暂不支持ARM架构）
  • 核心依赖：Docker 20.10.x及以上版本 + Docker Compose v2.x及以上版本
  • 网络条件：服务器需能访问互联网，用于拉取Docker镜像和项目依赖包

3. 前期检查要点

登录服务器后，先执行以下命令检查环境，避免部署中踩坑：

# 检查Docker版本（需≥20.10.x）
docker --version
# 检查Docker Compose版本（需≥v2.x）
docker compose version
# 检查服务器架构（需返回x86_64）
uname -m

若未安装Docker或版本过低，需先完成环境配置（下文附详细安装步骤）。

二、分步部署流程：从环境搭建到系统启动

1. 安装Docker与Docker Compose（新手必看）

以Ubuntu系统为例，执行以下命令一键完成环境安装，复制粘贴即可：

# 1. 更新系统包，避免依赖冲突
sudo apt-get update && sudo apt-get upgrade -y

# 2. 安装Docker所需依赖组件
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common

# 3. 添加Docker官方GPG密钥，确保安装包安全性
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo apt-key add -

# 4. 添加国内Docker软件源，提升下载速度
sudo add-apt-repository "deb [arch=amd64] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable"

# 5. 安装Docker Engine核心组件
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# 6. 启动Docker服务并设置开机自启
sudo systemctl enable --now docker

# 7. 配置国内镜像加速，解决拉取镜像慢的问题
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": ["https://docker.mirrors.ustc.edu.cn"]
}
EOF
sudo systemctl daemon-reload && sudo systemctl restart docker

# 8. 安装Docker Compose（v2.x版本）
sudo curl -L "https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

CentOS系统用户可替换对应yum命令，核心步骤一致，重点确保Docker服务正常启动。

2. 两种部署方式：新手一键安装 vs 手动定制部署

方式一：一键安装（推荐新手，10分钟完成）

这是最简单的部署方式，无需手动配置文件，执行一条命令即可自动完成所有操作：

# 切换root权限（避免权限不足导致部署失败）
sudo -i

# 执行官方一键部署脚本
bash -c "$(curl -fsSLk https://release.baizhi.cloud/panda-wiki/manager.sh)"

执行后按终端提示操作：

  1. 输入数字1选择”安装”选项；
  2. 无需修改默认端口（2443），直接回车确认；
  3. 等待5-10分钟（取决于服务器网速），期间会自动拉取镜像、配置数据库；
  4. 出现”SUCCESS”提示即部署完成，记录终端输出的访问地址、用户名（admin）和默认密码。

方式二：手动部署（适合有定制需求的用户）

适合需要修改端口、自定义存储路径的场景，步骤如下：

# 1. 克隆PandaWiki源码到服务器
git clone https://gitcode.com/gh_mirrors/pa/PandaWiki.git
cd PandaWiki

# 2. 创建并编辑docker-compose.yml配置文件
vim docker-compose.yml

粘贴以下基础配置内容（可根据需求修改端口和存储路径）：

version: '3'
services:
  api:
    build:
      context: ./backend
      dockerfile: Dockerfile.api
    ports:
      - "2443:8080"  # 左侧2443为对外端口，可自定义修改
    volumes:
      - ./data:/app/data  # 数据存储路径，建议保留默认
    depends_on:
      - postgres
    restart: always

  postgres:
    image: postgres:14
    environment:
      POSTGRES_USER: panda
      POSTGRES_PASSWORD: panda123
      POSTGRES_DB: panda_wiki
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    restart: always

保存配置后，执行启动命令：

# 构建并启动服务
docker compose up -d
# 查看启动状态，确保所有服务都为running
docker compose ps

3. 系统访问与初始化

  1. 打开浏览器，输入部署完成后提示的访问地址（格式：http://服务器IP:2443）；
  2. 输入默认用户名admin和终端显示的密码，首次登录需修改密码（建议包含大小写字母+数字，提升安全性）；
  3. 进入系统后，先完成基础配置：设置站点名称、上传Logo、配置时区（默认UTC，建议改为Asia/Shanghai）。

三、部署后必做：基础配置与安全加固

1. 核心配置优化

  • 存储配置：检查数据存储路径是否正确，确保磁盘空间充足，避免因空间不足导致服务异常；
  • 端口防护：若服务器暴露在外网，建议在防火墙中限制2443端口的访问权限，仅允许内部IP访问；
  • AI功能配置：进入”系统设置-AI模型”，对接百智云、通义千问等大模型API，解锁AI创作、AI搜索功能。

2. 安全设置要点

  • 密码修改：首次登录后立即修改默认密码，避免弱密码被破解；
  • 权限管理：创建不同角色账号（编辑者、读者），根据团队需求分配权限，避免全员拥有管理员权限；
  • 备份策略：定期备份数据目录（./data和./pgdata），可设置定时脚本自动备份，防止数据丢失。

四、常见问题排查：解决部署中的坑

1. 部署脚本执行失败

  • 问题原因：网络超时或权限不足；
  • 解决方案：切换root权限重新执行脚本，若拉取镜像慢，检查Docker镜像加速配置是否生效。

2. 浏览器无法访问系统

  • 问题原因：端口未开放或服务未启动；
  • 解决方案：
    1. 执行docker compose ps检查api服务是否为running状态；
    2. 开放2443端口：Ubuntu执行sudo ufw allow 2443，CentOS执行sudo firewall-cmd --permanent --add-port=2443/tcp && sudo firewall-cmd --reload；
    3. 检查服务器安全组是否放行2443端口（云服务器需在控制台配置）。

3. 登录提示密码错误

  • 问题原因：默认密码记录错误；
  • 解决方案：执行docker compose logs api查看日志，找到包含”password”的行，获取正确默认密码。

4. 服务启动后频繁崩溃

  • 问题原因：服务器内存不足（常见于1核2GB配置）；
  • 解决方案：升级服务器内存至4GB以上，或关闭其他占用内存的服务，减少系统负载。

五、日常维护：升级与备份指南

1. 版本升级

PandaWiki开源版迭代频繁，升级步骤如下：

# 进入项目目录
cd PandaWiki
# 拉取最新源码
git pull
# 重新构建并启动服务
docker compose down && docker compose up -d

2. 数据备份与恢复

  • 备份：直接打包数据目录即可，命令：tar -zcvf panda_backup.tar.gz ./data ./pgdata；
  • 恢复：将备份文件上传至新服务器，解压到PandaWiki目录下，再执行docker compose up -d。

按照以上步骤操作，就能稳定运行PandaWiki开源版，享受AI驱动的智能知识库服务。如果需要对接企业内部系统（如钉钉、飞书）或进行二次开发，可参考官方文档进一步配置。

© 版权声明
文章版权归作者所有，未经允许请勿转载。

相关文章

暂无评论

none
暂无评论...
添加小工具
点此为“正文侧边栏”添加小工具