type
Post
status
Published
date
Nov 23, 2025
slug
summary
记录了在 Ubuntu 云服务器上部署 PandaWiki 的全过程，包括环境搭建、反向代理配置、SSL 证书申请、域名跳转等关键步骤，以及实际遇到的典型问题与解决方案。
tags
PandaWiki
category
技术分享
icon
password
URL
本文完整记录我在腾讯云 Ubuntu 22.04 虚拟机上部署 PandaWiki 智能问答系统 的全过程。目标是通过 https://hnsoho.com 安全、稳定地访问前端服务，并实现 www 子域名自动跳转。过程中踩了不少坑，也积累了宝贵经验，特此分享，供参考。
一、项目背景
PandaWiki 是一款基于 RAG + LLM 的开源智能问答系统，特别适用于政策解读、知识库问答等场景，需满足：
- 对外提供 Web 访问入口
- 支持 HTTPS 加密
- 域名统一（
www.hnsoho.com→hnsoho.com）
- 后台管理仍可通过 IP+端口访问
二、部署环境
- 云服务器：腾讯云 CVM（Ubuntu 22.04 LTS）
- 公网 IP：
xxx.xxx.xxx.xxx
- 域名：
hnsoho.com（已解析 A 记录至服务器 IP，含www子域名）
- 已安装：Docker + Docker Compose
- PandaWiki 版本：v1.0（通过官方
docker-compose.yml启动）
三、第一步：一键安装PandaWiki确认服务运行状态
使用官方命令一键安装PandaWiki，不再赘述，进入项目目录启动服务：
通过
docker compose ps 查看容器，发现主要服务包括：panda-wiki-app（Next.js 前端）
panda-wiki-caddy（内置网关）
panda-wiki-raglite（后端 API）
关键测试：
直接在服务器本地 curl 测试不同端口：
✅ 结论：前台用户访问应指向
http://127.0.0.1:8080，而非 2443（后者是后台管理端口）。💡 教训：不要盲目相信 docker compose ps 的端口映射显示，以实际网络行为为准。
四、第二步：配置 Nginx 反向代理（HTTP 阶段）
为后续申请 SSL 证书，先配置纯 HTTP 的 Nginx 服务。
1. 创建站点配置
2. 创建验证目录并授权
3. 重载 Nginx
五、第三步：申请 Let's Encrypt 证书（使用 acme.sh）
1. 安装 acme.sh（国内镜像）
因 GitHub 在国内访问不稳定，采用 Gitee 源：
2. 申请多域名证书（含 www）
⚠️ 踩坑记录：初次尝试因/www/wwwroot/default目录属主为root，导致acme.sh（以ubuntu用户运行）无法写入验证文件，报错Permission denied。解决：执行sudo chown -R ubuntu:ubuntu /www/wwwroot/default彻底移交所有权。
✅ 成功后，证书生成于：
/home/ubuntu/.acme.sh/hnsoho.com/fullchain.cer
/home/ubuntu/.acme.sh/hnsoho.com/hnsoho.com.key
六、第四步：启用 HTTPS 并配置 301 跳转
完整 Nginx 配置（含 www 跳转）
重载生效
七、第五步：检查安全组与 DNS
- ✅ DNS：确保
hnsoho.com和www.hnsoho.com均解析至服务器 IP
- ✅ 安全组：在腾讯云控制台开放 TCP 80 和 443 端口（否则外部无法访问 HTTPS）
🔥 常见误区：即使 Nginx 配置正确，若云平台安全组未开放 443，浏览器会提示 “ERR_CONNECTION_REFUSED”。
八、最终效果验证
✅ 达成目标：
- 用户可通过
https://hnsoho.com安全访问
- 输入
www.hnsoho.com自动 301 跳转
- 证书有效，无安全警告
- 后台仍可通过
https://<IP>:2443管理（忽略证书错误即可）
九、经验总结
问题 | 原因 | 解决方案 |
curl :8080 成功但 :2443 失败 | 误判服务入口端口 | 以实际 curl 测试为准，选 8080 |
acme.sh 写入权限拒绝 | 目录属主为 root | chown ubuntu:ubuntu |
www 访问失败 | 证书未包含 www 或 Nginx 未监听 | 申请多域名证书 + 单独 server 块处理跳转 |
ERR_CONNECTION_REFUSED | 安全组未开 443 | 云平台开放 443 端口 |
十、后续维护建议
- 自动续期：
acme.sh已配置 cron 任务，无需手动干预
- 备份证书：定期备份
/home/ubuntu/.acme.sh/hnsoho.com/
- 监控服务：可配合
systemd或docker compose restart确保 PandaWiki 常驻运行
🌟 结语技术部署没有捷径，唯有“测试 → 报错 → 分析 → 解决”的循环。希望这篇记录能帮你少走弯路。PandaWiki 功能强大，搭配 HTTPS 域名后，真正实现了“安全、专业、可用”的智能问答服务。
—— 龚老师 · 三亚中瑞 · 海南自贸港数字化实践者
附：相关链接
- PandaWiki GitHub：https://github.com/chaitin/PandaWiki
- 作者:Miro
- 链接:http://miro.cx/article/2b44b0d4-ee78-80bd-b1c3-f1045e21c601
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。
