PandaWiki 全维度使用手册

一、平台介绍

1. 基础概况

PandaWiki 是由长亭科技研发、百智云运营的 AI 原生开源知识库系统。

• 开源协议：遵循 AGPL-3.0 开源协议。
• 部署形式：支持 GitHub 开源项目（chaitin/PandaWiki）及私有化部署。
• 核心优势：主打一站式搭建，支持产品文档、技术 Wiki、客服 FAQ、独立博客四类站点。
• 官方文档：https://pandawiki.docs.baizhi.cloud/node/0197160c-782c-74ad-a4b7-857dae148f84

2. 开源协议核心规则（AGPLv3）

用户在使用本系统时需严格遵守以下规则：

1. 免费使用：免费使用、修改代码、商用均无软件授权费。
2. 源码开源义务：若修改源码并对外部署（无论是公网还是内网服务），修改后的代码必须同步开源。
3. 二次分发：若将程序进行二次分发，必须沿用 AGPL-3.0 协议进行开源。

3. 产品定位

PandaWiki 与传统知识库软件（如 Confluence、Wiki.js）相比，具有显著差异化优势：

• 轻量部署：支持 Docker 一键部署。
• 原生智能：内置 AI 能力，无需额外配置大模型即可启动基础对话。
• 成本优势：无强制年费，支持私有化存储数据，解决传统系统收费昂贵及数据上云不安全痛点。

二、核心主要功能

（一）AI 智能化模块（产品核心）

这是区别于传统 Wiki 的最大亮点，支持接入多种大模型：

• AI 辅助创作：支持文档续写、润色、生成 API 文档/FAQ/目录，并允许自定义提示词。
• AI 语义问答：基于站内知识库内容智能答疑，可嵌入 IM 机器人对外提供问答服务。
• AI 智能检索：采用语义搜索算法而非简单的关键词匹配，实现跨文档精准定位。
• 模型接入支持：支持接入 OpenAI、DeepSeek、通义千问、Kimi 或 Ollama 本地私有化大模型。

（二）文档编辑与导出

• 双格式编辑器：支持富文本、Markdown、HTML 混合编辑，具备实时预览功能。
• 多格式导出：支持 Word、PDF、Markdown、HTML 全格式离线导出。
• 版本管控：提供文档全量历史记录、版本回滚、修改留痕及多人协同编辑功能。

（三）内容批量导入（低成本迁移）

提供 4 种低成本导入旧文档的方式：

• 文件导入：支持单个或多个离线文件（PDF、MD、Word）。
• 网页抓取：支持单页网页 URL 抓取。
• 整站爬取：支持全站 Sitemap 批量爬取。
• 订阅同步：支持 RSS 订阅自动同步内容。

（四）第三方集成能力

• 网页挂件：生成嵌入代码，可挂载至官网或产品页，充当在线帮助中心。
• IM 机器人：对接钉钉、飞书、企业微信，群内@机器人自动查询知识库并回复。
• 单点登录 SSO：支持对接企业内部 OA 或 LDAP 实现统一账号登录。

（五）权限管理（企业合规必备）

• RBAC 细粒度权限：支持管理员、编辑、只读、访客等多级分级。
• 资源隔离：可按知识库、单文档设置访问权限，支持部门文档隔离。
• 合规场景：满足金融、医疗等行业对数据隔离和访问控制的合规要求。

三、适用人群与落地场景

1. 企业团队（主力用户）

• 研发/技术团队：用于编写 API 手册、开发规范、故障方案及技术 Wiki，替代 Confluence 以降低部署成本。
• 产品团队：用于管理需求文档、版本说明书及产品手册。
• 客服团队：维护产品 FAQ 与故障排查库，对接企微机器人实现自动答疑。
• 运营/行政：用于沉淀 SOP 流程、规章制度及活动方案库。

2. 个人/自由职业者

• 程序员：用于整理个人技术笔记或搭建独立博客。
• 学习者：用于课程资料与读书笔记的结构化归档，利用 AI 快速检索知识点。

3. 机构与组织

• 培训机构：构建课件知识库。
• 自媒体：结合独立博客与素材库管理。
• 中小政务单位：构建内部公文库或通知发布平台。

四、免费与付费详情

1. 开源私有化部署版（永久免费，推荐）

此版本遵循 AGPL 协议，适合有运维能力的团队或个人。

• 软件成本：100% 免费，无功能阉割，无用户数限制。
• 允许商用：遵循 AGPL 协议即可商用。
• 自费成本：
• 大模型 API 费用：若使用云端大模型（如 GPT、DeepSeek）按量计费；若使用 Ollama 本地模型则无 API 费。
• 服务器成本：需自备服务器/NAS。个人可用闲置电脑或 NAS 实现零成本部署。

2. 百智云 SaaS 托管版（按需付费）

适合无运维团队或不想自建服务器的企业。

• 免费试用：提供有限的名额，包含知识库数量及存储空间限制。
• 付费套餐：按团队人数、存储空间及 AI 调用量阶梯订阅。
• 选型建议：有运维能力选私有化免费版；零技术团队选 SaaS 付费版。

3. 定制服务

• 收费项目：官方提供私有化定制部署、企业专属二开、等保适配（针对金融/医疗行业）。
• 性质：按项目报价，为可选服务，非强制。

五、详细使用指南（从部署到落地 5 步）

步骤 1：环境准备

• 硬件最低要求：2G 内存服务器、NAS 或闲置电脑。
• 系统兼容性：支持 Linux、Windows、群晖/极空间 NAS 等环境。
• 环境依赖：建议安装 Docker（一键部署必备）；若无 Docker，可使用官方 shell 脚本安装。

步骤 2：一键部署（2 种方式）

方式 A：Docker 极简部署（推荐）

复制以下命令并在服务器终端执行：

bash

docker run -d --name pandawiki -p 8080:80 chaitin/pandawiki
docker run -d --name pandawiki -p 8080:80 chaitin/pandawiki

• 访问地址：服务器 IP:8080
• 注意：系统生成初始管理员账号密码后，请立即登录修改。

方式 B：官方一键脚本（NAS/Linux通用）

复制以下命令执行交互式安装：

bash

bash -c "$(curl -fsSL https://pandawiki.docs.baizhi.cloud/install.sh)"
bash -c "$(curl -fsSL https://pandawiki.docs.baizhi.cloud/install.sh)"

• 流程：交互式选择安装目录，自动拉取组件，安装完成后记录内网地址和管理员账号。

步骤 3：后台初始化配置

1. 配置大模型（必填）：

• 路径：后台 → 系统设置 → 模型配置。
• 操作：填入 API 密钥（云端模型）或 Ollama 本地地址（如 http://ollama:11434）。
• 验证：测试连通性并保存。

1. 创建知识库：

• 操作：新建分类（如产品库、技术库、FAQ 库）。
• 权限：设置对应成员组的权限。

1. 基础参数设置：

• 修改站点名称、域名及前台主题（前台供用户访问，后台供编辑使用）。

步骤 4：文档导入与内容创作

1. 存量文档处理：

• 使用 URL、Sitemap 或批量文件导入历史资料。

1. 新建文档：

• 利用编辑器书写，或使用 AI 一键生成初稿。
• 对 AI 生成内容进行优化和审核。

1. 分类管理：

• 按目录树结构对文档进行归档。

步骤 5：对外落地使用

1. 对内协作：添加团队成员，分配读写权限。
2. 对外服务：

• 发布公网域名作为官网帮助中心。
• 生成网页挂件嵌入官网。
• 配置钉钉/飞书机器人，实现群内智能问答。

六、实操避坑清单

高频踩坑点与解决方案，请务必收藏查阅

1. 部署类风险

• ❌ 坑 1：默认 80 端口被占用现象：Nginx 或 Apache 占用 80 端口，导致 PandaWiki 页面无法打开。
• ✅ 方案：部署时修改映射端口，例如 -p 8090:80，并使用新端口访问。
• ❌ 坑 2：服务器内存不足现象：服务器内存小于 2G，启动后频繁崩溃。
• ✅ 方案：扩容内存；个人 NAS 优先使用 4G 以上闲置设备，并关闭多余容器以释放资源。
• ❌ 坑 3：忘记初始管理员密码✅ 方案：进入 Docker 容器，通过环境变量重置 ADMIN_PASSWORD 密码。

2. AI 配置风险

• ❌ 坑 1：AI 无响应现象：配置大模型后 AI 无法调用，问答无反应。
• 排查：检查 API 密钥是否正确、接口地址是否写错、模型余额是否耗尽；本地 Ollama 需提前拉取对应模型（如 ollama pull qwen）。
• ❌ 坑 2：回答内容无关✅ 方案：开启“知识库绑定向量检索”，限制 AI 仅基于站内文档作答，关闭全局大模型自由生成模式。

3. 内容与迁移风险

• ❌ 坑 1：批量导入乱码现象：大批量 Sitemap 导入导致文档乱码或丢失。
• ✅ 方案：分批导入（单次建议不超过 50 页），导入前备份原文档，并确保站点编码设置为 UTF-8。
• ❌ 坑 2：AI 内容错误现象：过度依赖 AI 自动生成导致内容错误。
• ✅ 规范：AI 生成初稿后必须人工校验、修改后再发布上线。

4. 开源合规与商用风险（AGPL 协议红线）

• ❌ 坑 1：商用不开源源码现象：修改源码后私有化对外提供服务（内网/公网），但不公开源码。
• ✅ 方案：必须将修改后的源码托管至 GitHub 或 Gitee 进行开源；仅本地单机自用且不对外提供服务，无需开源。

5. 权限与安全风险

• ❌ 坑 1：权限过大导致泄露现象：全团队开放管理员权限，导致敏感技术文档泄露。
• ✅ 方案：实施精细化 RBAC，编辑仅可修改对应知识库，普通成员设为只读，核心资料单独设置白名单。
• ❌ 坑 2：公网部署无防护现象：部署公网未修改默认密码，被恶意入侵。
• ✅ 必做：首次登录即修改为高强度密码；公网部署添加反向代理和防火墙，限制后台 IP 访问。

6. 运维风险

• ❌ 坑 1：数据丢失现象：从不备份数据库，容器误删后文档全丢。
• ✅ 方案：每周定时备份容器内 PostgreSQL 数据库，备份文件存放至异地（云盘/NAS）。

七、补充资源

• 官方文档：https://pandawiki.docs.baizhi.cloud
• GitHub 开源地址：https://github.com/chaitin/PandaWiki
• 社区交流：百智云论坛 https://baizhi.cloud/discussion
• 交流群：官方微信交流群