企业官网建设流程全解析

• 后端
• 前端
• 人工智能
• AI 应用
• RAG
• 知识管理

PandaWiki 是一款 AI 大模型驱动的开源知识库搭建系统，帮助团队快速构建产品文档、技术文档、FAQ 与博客站点，并提供 AI 创作、AI 问答、AI 搜索三大智能化能力。本文以仓库根目录 README.md 为主线，结合 backend/config/config.go、backend/handler/v1/model.go 等源码，完整讲解从 Docker 环境准备、一键安装、控制台登录，到 AI 模型接入、知识库创建与内容导入的实战全流程，读完即可上手搭建属于自己的智能 Wiki 站点。

PandaWiki 是什么

PandaWiki 是一个前后端分离的开源项目（仓库结构可参考 PROJECT_STRUCTURE.md），主体由以下几部分组成：

• 后端服务（backend/）：使用 Go 语言编写，提供 API、业务逻辑与数据存储，入口位于 backend/cmd/api/main.go，其中panda-wiki-api提供 HTTP 服务，panda-wiki-consumer负责消费消息队列中的异步任务（如文档解析、RAG 学习）。
• 管理后台（web/admin/）：React + TypeScript 编写的控制台，用于管理知识库、用户、模型与站点。
• Wiki 网站前台（web/app/）：面向访问者的知识库阅读与 AI 问答界面，支持网页挂件、钉钉/飞书/企业微信机器人等形态。
• RAG SDK（sdk/rag/）：面向开发者的检索增强生成（Retrieval-Augmented Generation）工具包，包含数据集、文档、检索等能力。

它的核心价值在于：以"知识库"为单位组织文档，为每个知识库分别生成独立的 Wiki 网站，并用大模型为文档赋予创作、问答与搜索能力。

功能与特色

• AI 驱动智能化：AI 辅助创作、AI 辅助问答、AI 辅助搜索，底层依赖大模型与 RAG 检索能力。
• 强大的富文本编辑能力：兼容 Markdown 与 HTML，支持导出为 Word、PDF、Markdown 等多种格式。
• 轻松与第三方应用集成：可做成网页挂件挂在其他网站上，也可做成钉钉、飞书、企业微信等聊天机器人（对应实现位于 backend/pkg/bot/）。
• 通过第三方来源导入内容：支持按网页 URL 导入、通过网站 Sitemap 导入、通过 RSS 订阅、通过离线文件导入等（对应实现位于 backend/pkg/anydoc/ 与 backend/usecase/crawler.go）。

系统架构与部署形态一览

在正式安装前，先理解系统的运行形态有助于排障。从源码与 Docker 构建文件可以梳理出部署的基本组成：

• API 服务与消费者服务：Dockerfile 同时构建panda-wiki-api与panda-wiki-migrate两个二进制（见 backend/Dockerfile.api），启动时会先执行数据库迁移，再启动 API 服务；而消费者服务（backend/cmd/consumer/main.go）负责启动 MQ 消费者处理异步任务。
• 基础组件：从 backend/config/config.go 的默认配置可以看到，系统依赖 PostgreSQL（数据库）、NATS（消息队列，mq.type默认nats）、Redis（缓存）、MinIO（S3 对象存储）与 Caddy（反向代理/证书管理，默认配置caddy_api）。
• RAG 检索组件：默认rag.provider为ct，对接ct_rag服务用于文档切片、向量化与检索。

上述是源码中体现的默认拓扑；实际一键安装时，官方安装脚本会以 Docker 容器形式编排这些组件，读者无需手工搭建。

环境要求

安装 PandaWiki 需要一台支持 Docker 20.x 及以上版本的 Linux 服务器，并使用 root 权限登录执行安装命令。安装脚本会完成环境检查、镜像拉取与容器编排，整个过程会持续几分钟，请耐心等待。

安装 PandaWiki

登录服务器后，直接执行官方提供的一键安装命令：

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

执行过程中按照命令提示的选项进行安装即可。安装完成后，命令终端会输出如下形式的部署结果信息：

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

请妥善保存输出的"访问地址、用户名、密码"，后续登录与配置都会用到。从后端入口代码 backend/cmd/api/main.go 可以看出，API 服务会读取配置中的HTTP.Port并启动 HTTP 服务，同时会执行证书初始化检查（setup.CheckInitCert），这也是安装阶段需要等待几分钟的原因之一。

登录 PandaWiki 控制台

使用浏览器打开安装输出中的"访问地址"，即可看到 PandaWiki 控制台的登录入口。使用输出的"用户名（admin）"和"密码"登录即可进入控制台。

控制台（web/admin/）是日常管理入口，你可以在这里：

• 管理知识库并上传文档，等待系统完成文档学习；
• 配置 AI 模型与模型参数；
• 管理导航、用户权限、访问控制与统计信息等。

配置 AI 模型：让 AI 能力生效的前提

PandaWiki 是由 AI 大模型驱动的 Wiki 系统，在未配置大模型的情况下，AI 创作、AI 问答、AI 搜索等功能无法正常使用。

首次登录时会提示需要先配置 AI 模型，可自行选择一键配置或手动配置：

两种配置模式

从源码 backend/domain/model.go 与 backend/handler/v1/model.go 可以看到，模型配置支持auto（自动）与manual（手动）两种模式（SwitchModeReq.Mode字段，取值manual/auto）：

• 一键配置（自动模式）：填写百智云（BaiZhiCloud）API Key 即可自动接入对话、向量化等模型，适合希望最快跑通全流程的用户；SwitchModeReq中的AutoModeAPIKey与AutoModeProvider即对应此模式。
• 手动配置（手动模式）：自主填写供应商、模型名称、BaseURL、API Key 等字段，适合已有其他大模型服务商的用户。

模型类型与参数说明

模型中Type字段支持以下类型（ModelType，见 backend/domain/model.go）：

手动配置时还会用到以下字段（BaseModelInfo）：

• provider：模型供应商（如BaiZhiCloud）；
• model：模型名称；
• base_url：服务地址（必填）；
• api_key：API 密钥；
• api_header：自定义请求头（可选）；
• api_version：Azure OpenAI 等场景下的 API 版本号（可选）。

此外，模型还支持高级参数（ModelParam）：context_window（上下文窗口）、max_tokens（最大生成长度）、temperature（采样温度）以及support_images、support_prompt_cache等能力开关。

保存前，控制台会调用/api/v1/model/check接口对模型连通性进行校验（对应 backend/handler/v1/model.go 中的CheckModel，底层通过 ModelKit 发起真实请求验证）；也可通过"获取供应商支持模型列表"接口（/api/v1/model/provider/supported）拉取某个供应商当前可用的模型清单，避免手填名称出错。

后端模型配置的底层实现

在 backend/domain/model.go 中，Model结构体记录了每次调用的 token 消耗（PromptTokens、CompletionTokens、TotalTokens），方便控制台统计用量。配置完成后，系统会将模型元数据（供应商、名称、API Key、BaseURL、温度等）转换为 ModelKit 的ModelMetadata（见ToModelkitModel），供 LLM 调用链路统一使用。

创建知识库

"知识库"是一组文档的集合，PandaWiki 会根据知识库中的文档，为不同的知识库分别创建对应的"Wiki 网站"。

在控制台创建知识库时，需要为知识库规划对外访问方式。从领域模型 backend/domain/knowledge_base.go 可以看到，每个知识库都带有AccessSettings（访问设置），包括：

• ports/ssl_ports：HTTP / HTTPS 访问端口；
• hosts：绑定的域名或主机；
• public_key/private_key：HTTPS 证书；
• base_url：自定义基础访问地址；
• simple_auth：简单密码访问（开启后需输入密码才能阅读）；
• enterprise_auth：企业认证（对接统一登录源）；
• is_forbidden：是否禁止访问。

系统会根据这些设置自动推导出 Wiki 网站的访问地址（见GetBaseUrl方法：优先使用base_url，否则依据 hosts 与端口拼接 http/https 地址）。也就是说，每个知识库既可以完全公开，也可以设置密码保护或企业认证。

创建完成后，即可向知识库上传文档，系统会将文档纳入 RAG 学习流程，等待学习成功后可进行 AI 问答。

通过第三方来源导入内容

除了直接上传文档，PandaWiki 还支持从多种第三方来源批量导入内容。从爬虫 API 定义 backend/api/crawler/v1/crawler.go 与用例层 backend/usecase/crawler.go 可以看到，crawler_source支持以下来源：

导入任务通过消息队列异步执行，任务状态包含pending、in_process、completed、failed四种（见 backend/consts/crawler.go），控制台可查询任务结果并选择性地将解析出的文档加入知识库。

开始使用

如果你顺利完成了以上步骤，那么恭喜你，属于你的 PandaWiki 已经搭建成功，接下来你可以：

• 访问控制台来管理你的知识库并上传文档，等待文档学习成功；
• 访问Wiki 网站使用知识库，并测试 AI 问答效果。

在 Wiki 网站上，访问者可以浏览文档目录、全文搜索，并与知识库进行 AI 问答——系统基于 RAG 技术先从知识库中检索相关片段，再交由对话模型组织回答，从而让问答结果有据可依（RAG 相关能力可参考 sdk/rag/ 中的数据集、文档与检索接口定义）。

遇到问题怎么办

如在使用产品过程中遇到问题，可以通过以下方式获取帮助：

• 查阅官方文档中的"常见问题"章节，更多内容请参考官方文档目录；
• 不想翻文档时，使用官方文档站内的 AI 问答快速获取答案；
• 加入官方交流群（images/wechat.png 为交流群二维码），与更多用户及官方人员交流经验、获得帮助。

贡献与许可证

欢迎通过提交 Pull Request 或创建 Issue 来帮助改进项目。

本项目采用GNU Affero General Public License v3.0 (AGPL-3.0)许可证（详见 LICENSE），这意味着：

• 你可以自由使用、修改和分发本软件；
• 你必须以相同的许可证开源你的修改；
• 如果你通过网络提供服务，也必须开源你的代码；
• 商业使用需要遵守相同的开源要求。

附录：部署相关配置参考

对于需要深度定制部署（如自建组件、替换默认存储与消息队列）的场景，可以参考后端配置模块 backend/config/config.go。配置采用"默认值 + 配置文件 + 环境变量覆盖"三级机制：

• 默认值：内置 PostgreSQL（panda-wiki-postgres）、NATS（nats://169.254.15.13:4222）、Redis（panda-wiki-redis:6379）、MinIO（panda-wiki-minio:9000）等默认连接；
• 配置文件：支持config.yml覆盖，通过 viper 加载；
• 环境变量覆盖：敏感信息优先以环境变量注入，例如：

数据库迁移脚本位于 backend/store/pg/migration/，API 服务启动时会自动执行迁移（见 backend/Dockerfile.api 中的panda-wiki-migrate），确保表结构与版本匹配。

按照本指南完成安装、模型配置与知识库创建后，你就拥有了一个可对外发布、可 AI 问答、可持续从第三方来源导入内容的智能知识库站点。

• 后端
• 前端
• 人工智能
• AI 应用
• RAG
• 知识管理