俗世客的思行小筑

Docker 部署内网穿透客户端：客户端只出站连服务端 47800，开启 WEB_ENABLE 后才监听 47802 的 Web 配置界面，默认绑所有接口。部署前须运行 init.sh 并授权 data/ 给 uid 10001，否则配置库降级、界面配置重启丢失。配置优先级为 client.env、Web 界面、.env、默认值；改 client.env 需重建容器，Web 保存即时生效。容器内 127.0.0.1 是自身，宿主机服务用 host.docker.internal，静态隧道用 TUNNELS_FILE。验证看 /healthz 和 X-Proxy-By；隧道变更后反代规则不会自动更新，需重载或重启服务端。实测云端链路可打通，升级不影响 data/。

飞牛 OS NAS 用 Docker 部署内网穿透客户端一次成功，三条隧道全通，服务端在线数由 0 变 1。容器场景必须用隧道文件配置，简写参数会固定为容器内 127.0.0.1，不适用。域名按全库查占用，不能跨客户端复用；落入泛域的新隧道云端无需改动。改隧道文件只需重启，改凭据文件必须强制重建。验证应比对经隧道与 NAS 直连后端的哈希，并查代理头；流量统计表存窗口增量而非累计。1.2.0 起以配置库为权威。升级前若遇家目录权限导致 Docker 配置失败，可临时指定配置目录；旧容器名冲突先删再启动；实测仅一个泛域生效。

内网穿透系统云服务器部署包提供可直接部署的 compose、nginx 与 .env 配置及离线镜像，较本机版做了四项云环境调整：postgres 不映射宿主机端口，tunnel-server 的 nofile 提至 65535，容器加 no-new-privileges，资源上限由 .env 控制。部署前须确认 amd64/arm64 架构，安全组只放行 80、443、47800 等必要端口，勿开放 47801 和 5432；填写 EXTERNAL_IP、CERT_EMAIL 并替换 nginx 中的面板与隧道域名。自动生成的强随机凭据需立即保存，CONFIG_ENCRYPT_KEY 不可更改。证书用 HTTP-01 申请，续期后手动重启 nginx。发布包含服务端、客户端镜像与升级/自包含部署包，服务器无需联网。

系统采用控制面与数据面分离：每客户端一条持久控制连接负责鉴权、心跳与隧道注册，工作连接按需创建或池化；二者复用47800端口，靠首帧区分。HTTPS由Nginx终结，服务端按Host路由明文HTTP，工作连接由客户端主动发起，内网无需开放入站端口；启用yamux后以逻辑流替代新建TCP。控制协议用4字节大端长度加JSON，含登录、隧道下发、工作连接请求和心跳。47800对外，管理入口仅本机代理，TCP隧道池、HTTPS入口和转发范围按需对外。

Halo文章正文为HTML，MiniDocs为Markdown，因而Halo用HTML模板，MiniDocs与仓库.md用Markdown模板；Halo原生文章无front-matter，宜用正文元信息块记录版本、验证时间与环境。模板覆盖排错、README和教程长文，长文以H2为主章节并自动生成目录。代码高亮需正确标注语言，提示用引用块，图片和封面经编辑器或文章设置上传。附录A称本次纯文档整合零改动，产出README总纲，冲突以专项报告为准；验收含密钥零命中、分类标签73条断言、38个文档、44项回读和34表恢复，第3步为唯一写操作。

环境变量配置分两份模板：根 .env.example 69 项用于本机开发，deploy/cloud/.env.example 202 项用于云生产，含证书、DDNS、反代、转发、备份、告警及 compose 变量，不可混用。优先级为环境变量>.env>代码默认，约 60 项可在 Web 热改。上线前须改 JWT_SECRET、TOKEN_SALT、32 字节 CONFIG_ENCRYPT_KEY、ADMIN_PASSWORD、数据库密码，并保持 ALLOW_PRIVATE_UPSTREAM、BACKUP_INCLUDE_SECRETS 为 false。Halo 实际运行 Pro 2.26.1，镜像 tag 2.26 是滚动标签，锁定或回滚应按 digest；Halo 与 PostgreSQL 15.4 容器健康，端口 28090->8090，内网与公网健康检查均 200。

文档集记录 Halo 站点建设与内网隧道方案。已完成 Halo 2.26.1 基线、CLI 接通、插件安装、分类标签体系、38 节点 MiniDocs 知识库、页面菜单、Gitea 同步、备份恢复与安全审计。关键结论：访客 AI 问答、编辑器辅助创作、语义增强搜索均不可实现，根因是缺少访客端点、编辑器扩展、embedding 适配器及具体 RAG 检索实现；ai-assistant 因许可证未启用。文档约定用【实测】【推断】【未确认】标注可信度，凭据只用占位符，并给出 5 步最小复现路径；另附内网隧道架构、端口、网关与安全防护等目录。

隧道流量统计恒为0已在v1.0.4修复。根因是1.0.1把公网入口交给内置反代时只搬流量、未搬记账，统计仍只挂在数据面路径。修法是在反代隧道连接上记账，不包ResponseWriter，以覆盖HTTP、SSE、WebSocket，并须共用同一stats.Collector，否则会静默丢弃。验证需访问隧道3次确认增量非0，且未访问隧道仍为0。1.0.1还修复反代规则不自动同步和48080监听冲突，生产compose漂移须回写仓库。

如果你看到了这一篇文章，那么证明你已经安装成功了，感谢使用 Halo 进行创作，希望能够使用愉快。