開源 RAG 項目我之前主要圍繞 RAGFlow 寫了不少落地案例。RAGFlow 定位是大而全的企業級 RAG 引擎，所以社區里也一直有人吐槽：資源吃得多、處理慢。但這事兒某種程度上就是端到端全包（解析、切分、向量化、檢索、權限、工作流、評測）的代價，工程體量上去了，默認就不可能太輕。

如果你想找一款更輕量的開源方案，主要用來處理產品文檔、技術文檔、FAQ、博客等內容，那可以看看今天要介紹的 PandaWiki。一句話總結：PandaWiki 更像開源版的知識庫產品，而不是一個給工程師從零拼裝的 RAG 引擎。

這個項目實際我也是近期才注意到，GitHub 目前 8.6K Star，看趨勢圖下半年熱度是一路走高。我花了幾天集中測了下，確實有一些可圈可點的地方，這篇就抓大放小，來和各位說道說道。

這篇試圖說清楚：

PandaWiki 的手把手本地部署過程、知識庫操作流程演示、實際問答效果測試、衍生功能模塊盤點等。

以下，enjoy:

1、手把手本地部署

首先需要說明的是，PandaWiki 官方僅提供 Linux 環境的部署方案，關于官方配置教程網上已經非常多了。這篇我著重來介紹一下如何在 Mac（同樣適用于 Windows）上部署 PandaWiki 的完整步驟和必要修改。

https://pandawiki.docs.baizhi.cloud/node/01971602-bb4e-7c90-99df-6d3c38cfd6d5

1.1官方為什么只支持 Linux？

PandaWiki 的官方部署方案采用了 Docker 的 network_mode: host（主機網絡模式）。這是個非常聰明的設計選擇，容器直接共享宿主機的網絡棧，不需要任何端口映射。其次 Caddy 作為反向代理，可以根據用戶創建的 Wiki 站點動態監聽任意端口，這些端口自動對外可用。當然還有簡化架構的好處，不需要考慮 Docker 網絡內部的 DNS 解析和服務發現問題。

這個方案在 Linux 服務器上堪稱完美，用戶只需要一鍵腳本，就能快速啟動一個功能完整的 AI 知識庫。

但問題也隨之而來，network_mode: host在 Mac 和 Windows 上沒法用。因為Docker Desktop 在這兩個平臺上運行的架構完全不同，Linux里Docker 直接運行在宿主機內核上，Host 模式讓容器與宿主機共享同一個網絡命名空間。而Mac/Windows里，Docker 是運行在一個輕量級 Linux 虛擬機里，Host 模式只是讓容器共享虛擬機的網絡，而不是你的 Mac 或 Windows 的網絡。

換句話說，即使容器監聽了 0.0.0.0:8080（或其他你設置的端口號），你在瀏覽器里訪問 localhost:8080 也是訪問不到的,因為這個端口暴露在虛擬機里，而不是你的電腦上。

1.2為什么要做本地部署

我想看我文章的多數盆友，如果想嘗試下 PandaWiki，手里可能沒有一臺現成的 Linux 服務器。尤其是對配置服務器沒有經驗的朋友，配置安全組、開放端口、設置防火墻，還有搞域名和 SSL 證書這些，一個環節出了問題，可能心態就會崩掉。對只是想快速看看這個東西好不好用的嘗鮮需求來說，這個門檻確實太高了。

那在 Windows 上用 WSL 行不行？理論上可以，但實際操作起來相當折騰。需要先安裝配置 WSL 2（Windows Subsystem for Linux），然后在 WSL 里安裝 Docker，或者讓 WSL 使用 Windows 的 Docker Desktop（需要額外配置）。需要注意的是，網絡配置容易出問題，WSL 和 Windows 主機之間的端口轉發經常踩坑。對于不熟悉 Linux 的用戶，這個學習曲線也很陡峭。

所以在正式介紹PandaWiki的功能亮點前，先在開篇給大家一個新的本地部署的選項，讓大家能在自己的電腦上5 分鐘內跑起來，這樣再看下面這些內容才好復現具體測試。只要你電腦上裝了 Docker Desktop，復制粘貼幾條命令就能看到效果，這也才是嘗試新項目的時候快速上手應該有的狀態。我也是花了些時間研究官方的 docker-compose.yml，分析為什么它在 Mac 上跑不起來，然后一個問題一個問題地解決，最終整理出了一份可以直接復制使用的配置。（詳見下方復現處說明）

1.3三個核心改造點

具體的改造過程就不逐一拆解給大家看了，內容有點冗雜。核心看一下下方這個匯總的表格和下面三個改造點的總結，但當涉獵下即可，然后再接著去看這個具體的復現步驟。

這三個改造點環環相扣：

1、因為不能用 Host 模式，所以要改成 Bridge 網絡

2、改成 Bridge 后，原來的 Socket 共享方式失效，所以要用命名卷

3、Bridge 模式下端口不自動暴露，所以要手動映射

看完這個邏輯鏈條，應該就能大致理解整個改造的核心思路。

1.4具體復現步驟

環境要求

創建部署目錄

mkdir -p ~/pandawiki/deploy
cd ~/pandawiki/deploy

創建 .env 配置文件

cat > .env << 'EOF'
# 時區
TIMEZONE=Asia/Shanghai
# 容器網段
SUBNET_PREFIX=169.254.15
# 中間件密碼（請修改為你自己的隨機密碼，長度 > 8，僅數字字母）
POSTGRES_PASSWORD=YourSecurePassword123
NATS_PASSWORD=YourSecurePassword123
JWT_SECRET=YourSecurePassword123
S3_SECRET_KEY=YourSecurePassword123
QDRANT_API_KEY=YourSecurePassword123
REDIS_PASSWORD=YourSecurePassword123
# 管理后臺登錄密碼（請務必牢記）
ADMIN_PASSWORD=YourAdminPassword123
# 管理后臺訪問端口
ADMIN_PORT=2443
EOF

創建 docker-compose.yml

這部分內容太長，有需要請自行在網盤下載 docker-compose.yml，鏈接: https://pan.baidu.com/s/1w2dlMjkn6hrFFiFNnk-zTA 提取碼: 67um

啟動服務

docker compose up -d

首次啟動需要拉取鏡像，需要花點時間。

訪問管理后臺

管理后臺地址：https://localhost:2443

用戶名：admin

密碼：在 .env 中設置的 ADMIN_PASSWORD

?? 瀏覽器會提示"連接不安全"（因為是自簽名證書），點擊 高級 → 繼續訪問 即可。

注：密碼別用默認；端口范圍別和本機已有服務沖突（比如 8080/8081 常見沖突）。自簽名證書只是本地測試用，線上別這么搞。

創建 Wiki 站點

登錄后臺，點擊左側菜單進入創建流程

在「配置監聽」步驟中：

域名或 IP：填寫 localhost

HTTP 端口：勾選啟用，填寫 8081（可選 8081-8090）

HTTPS 端口：本地測試可以不勾選

完成創建后，訪問你的 Wiki 站點：http://localhost:8081

2、知識庫操作流程演示

完成上述所有的配置之后，首先選擇“文檔”模塊，可以注意到可以選擇創建文檔或者文件夾，文檔的導入方式有十來種，下面我主要演示本地導入的方式。

文檔格式常見的基本都支持，需要說明的是，在導入之后是需要點開具體文檔進行發布才會觸發“學習”（向量化）的動作。

每篇文章的開頭支持 AI 摘要，這個我試了下，效果還行。如果文檔內容比較長，可以試下這個功能。

我也導入了兩種不同格式的包含圖片的文檔，對比了下效果，其中一種 word 格式的，識別效果沒問題。

第二個是 PDF 格式，圖片嵌套在了其中的表格中，實際最后沒有正確識別到圖片。不過這個頁面布局確實復雜度比較高，無論是之前測試的 RAGFlow，包括像 MinerU 這樣專門的解析工具識別都不是很好，這種還是要盡可能的去做預處理再做導入。

3、實際問答效果測試

首先可以注意到的就是，PandaWiki 是同時支持了僅檢索文檔和智能問答兩種模式。保留了僅檢索文檔這個設計，我覺得其實很實用。

比如我之前歷史文章當中介紹到的售前智能報價 agent 的案例，這個項目在一期做落地的時候，核心就是幫助企業老板先通過向量相似度+BM25 的方式，快速的召回歷史上 7000 多份報價單里面最相似的幾份，后續再基于傳統的經典算法的一些模式識別加上 agent 的多步推理，逐步實現了報價單的半自動生成。

Image

下面的兩個問題測試主要圍繞智能問答這一部分功能。

3.1規章制度問答

這次上傳的測試文檔里面，包含了我在視頻課程里面講到的第一個規章制度問答的案例，回答的效果我整體覺得挺不錯的。

問題 1：條件判斷與多分支查詢

Q: `部門主管可以選擇什么艙位的機票？一天餐費是多少錢？`


- 設計陷阱：
  1. 機票：不是簡單的“經濟艙”，規章里有一個“連續飛行5小時”的特殊條件。
  2. 餐費：沒有固定金額，取決于“城市等級”這一變量。
- 預期標準回答：
  > 機票一般預訂經濟艙，但連續飛行超過5小時可預訂公務艙；餐費根據城市等級分別為150元、120元或100元。

這里我主要看：條件識別是否漏、答案是否把變量說清楚、引用是否到位。整體回答我覺得還是比較清爽，雖然只需要單一文檔就能夠回答，還是比較準確的識別到了關于“連續飛行 5 小時”的這個特殊條件的要求。

問題 2：跨文檔多跳推理

Q: `M3級別員工去上海出差住宿標準`


- 設計陷阱：這也是最難的一個問題。
  1. 第一跳：AI 必須先去《員工手冊》查到 `M3 = 部門總監`。
  2. 第二跳：AI 必須知道 `上海 = 一線城市`。
  3. 第三跳：去《差旅細則》表格找到“部門總監”+“一線城市”的交叉點。
- 預期標準回答：
  > 1000元/晚。思維鏈應包含：識別出M3為部門總監 -> 識別出上海為一線城市 -> 查表得出1000元。

這里我主要看：多跳是否真的跨文檔、是否能把‘概念映射→查表’走完。這部分回答依然是比較簡單明了，從這點可以看出，在基礎問答場景下，PandaWiki 的 RAG 產品化做的已經相對來說比較成熟了。

3.2圖文混答測試

前面在知識庫的部分提到了兩種類型的圖文文檔，有一種復雜 PDF 頁面布局識別的不夠準確。這部分我們就先暫時跳過，來著重演示下另外一個 word 格式的圖文內容回答。這也是我上周一篇文章當中剛介紹到的工控軟件售后問答場景的一個節選文檔。

Image

這類文檔的問答場景對于回答的圖文混排效果要求比較高，尤其是包含一些操作步驟類型的，需要有對應的圖示，回答才有一定的參考價值。先說結論，幾輪測試下來，我覺得整個回答的準確性和效果還是不錯。

4、衍生功能模塊盤點

以上把 PandaWiki 的知識庫問答部分做了一個快速的盤點，文章的最后再和大家快速過一下一些值得關注的衍生功能模塊。

4.1統計看板

這部分雖然是常規的 BI 看板，但不可或缺的原因是 rag 這種項目在上線前的各種測評，雖然可能能達到一定的預期效果，但是上線后能否長期使用，仍然依賴業務專家真實問答中的標注式反饋，這樣才能夠不斷的迭代優化知識庫。所以通過看板可以比較整體的把握一下系統的使用情況。

4.2反饋

在每個回答下面，可以通過顯示的點贊點踩來進行上述提到的人工標注。然后同步的就可以在反饋這個模塊進行查看，這也是技術人員進行系統優化的重要的 bad case 的來源。

4.3問答機器人

我在上一篇文章當中介紹工業軟件售后問答場景案例的時候有提到，很多知識庫試點項目失敗的真正原因，不是技術不行，而是上下文切換成本太高。用戶正在企業微信群里答疑，卻要切換到瀏覽器打開知識庫網頁，再復制答案發回去，這種體驗注定用不起來。

所以知識庫不應該是一個獨立的網站，而應該是一種能力，嵌入到用戶已有的工作流中。企業 IM 集成是優先級最高的方向：企微、釘釘、飛書的機器人，群里 @一下就能直接回復卡片式答案。其次是瀏覽器插件或側邊欄，讓用戶在 OA、CRM 等系統里直接提問。再往后是標準化的 API 和 SDK，方便客戶把知識檢索能力嵌入自有系統。更長遠來看，還可以發布為 MCP Server 或 LangChain Tool，讓各種 Agent 工作流能夠直接調用。這些集成的能力 PandaWiki 都已經做了對應接口適配，這也算是產品成熟度的體現之一。

5、寫在最后

整體測下來，我對 PandaWiki 的評價就一句話：它把“知識庫問答”這件事產品化做得比較完整，而且門檻確實低。如果你想要一個輕量、上手快、能很快跑出效果的知識庫開源方案，PandaWiki 值得花半小時親自裝一遍、測一遍。

開源項目好不好用，最后還是靠社區一起把邊界條件補齊。你在使用過程中遇到問題，建議直接開 Issue 反饋（記得帶復現步驟和日志）。GitHub 記得點個 Star，也算是個訂閱入口。地址 https://github.com/chaitin/PandaWiki

后面我如果再繼續深挖（比如：更復雜的圖文解析、不同 embedding/向量庫組合、以及 IM 機器人接入的效果），這篇點贊多的話再寫一篇續集。