知识库MaxKB 从零搭建 → AI智能体对外发布 技术清单（完整复盘）

知识库MaxKB 从零搭建 → AI智能体对外发布 技术清单（完整复盘）

说明：构建智能体机器人，嵌入主页发布，以下全部来自本次会话真实落地过程；带「💡讲解」的是原理说明。
采用多种技术， Docker 容器化层、 frp 内网穿透层，并对链路图、坑位表、总结做同步记录。

一、基础设施层

💡讲解：很多同学会把“主机厂商”和“DNS 厂商”搞混。HTTP 请求打到主机 IP 后由 Nginx 处理，但证书 DNS-01 挑战验证 TXT 记录时，只认域名解析在哪一家→ 所以走阿里云 DNS API，不走腾讯云。

二、Web 发布层（Nginx）

💡讲解：MaxKB 本身监听容器内部端口，对外不直接暴露，由 Nginx 反代出来；nginx.conf里证书路径固定指向C:/nginx/certs/ai.DQL5251.top-*.pem，所以证书覆盖后 reload 即可生效，配置文件一行不用改。

三、HTTPS 证书自动化层

💡讲解（自动续签完整链路）：

[Windows 任务计划 acme.sh.cron] 每天触发 │ ▼ [acme.sh --cron] ├─ 剩余 > 30 天 → Skip（不消耗 Let's Encrypt 配额） └─ 快到期 → dns_ali 自动加 TXT → 签发 → 覆盖 pem → nginx -s reload

证书替换是 acme.sh 钩子干的，不是计划任务直接 copy 文件。

四、Docker 容器化层（本次新增） 🆕

💡讲解：用 Docker 装 MaxKB 的最大好处是环境隔离、一键迁移、版本回滚。不用 Docker 就得在宿主机上装一堆 Python 依赖，版本冲突风险高；用容器后，docker compose up -d一条命令就能起服务，换机器也只需拷走 compose 文件 + volume 目录。

端口流向：容器 8080→（映射）→宿主机 8081→（frp 隧道 / 本地反代）→Nginx 8083→ 公网。

五、frp 内网穿透层 🆕

💡讲解：frp 解决的是"内网服务没有公网 IP / 被防火墙挡住"的问题。MaxKB 跑在本地内网机器上，frpc 主动向外建立长连接隧道，外部请求经公网 frps 转发进来，Nginx 再反代到 frps 暴露的端口。

最小配置示例：

frps.toml（腾讯云公网主机）：

bindPort = 7000 --auth.method = "token" --auth.token = "你的复杂随机token"

frpc.toml（内网机器）：

serverAddr = "腾讯云公网IP" serverPort = 7000 --auth.method = "token" --auth.token = "和frps一致的token" [[proxies]] name = "maxkb" type = "tcp" localIP = "127.0.0.1" localPort = 8081 # docker内部MaxKB端口8080，映射到宿主机后的8081 remotePort = 8082 # 远程端口8082 给到云主机， Nginx反代外部应用 8083

腾讯云安全组需放行：7000（控制面）、8083（数据面）、443/80（Nginx）。

六、MaxKB 应用本身

💡讲解：高级智能体适合多步编排、外部API串联；纯知识库问答选简易，稳定、好排查。

七、辅助工具链

八、端到端发布链路图（完整版）

[用户浏览器] │ https://ai.dql5251.top:8083 ▼ ┌─────────────────────────────────────────────────────┐ │ 腾讯云公网主机 │ │ │ │ [Nginx :8082 HTTPS 本地] │ │ │ proxy_pass │ │ ▼ │ │ [frps :8082] ◀────── TCP 隧道（TLS 加密）────────┐ │ │ │ │ │ └────────│────────────────────────────────────────────┘ │ │ │ ┌─────────────┘ │ ▼ │ [frpc]（内网机器） │ │ │ ▼ │ [宿主机 :8081] │ │ 端口映射 │ ▼ │ [Docker 容器 :8080] │ │ │ ▼ │ [MaxKB 服务] │ └─ 证书文件 ←── acme.sh 钩子自动覆盖 ▲ │ 每天由 Windows 任务计划 acme.sh.cron 触发 │ [阿里云DNS dns_ali 自动TXT验证]

端口流向一览：

九、本次踩过的典型坑（沉淀为经验）

十、技术栈全景一句话

Docker 容器化 MaxKB→frp 内网穿透打通公网→Nginx 反代 + Let’s Encrypt(dns_ali) 全自动证书 HTTPS 终结→阿里云 DNS 解析，
四层各司其职，实现"内网服务安全发布到公网、证书零人工续签"的完整闭环。

附录：分层速查表