部署 PandaWiki 全流程实录：从 Docker 到 HTTPS 域名访问

type

status

date

slug

summary

一、项目背景

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 端口