俗世客的思行小筑

Halo 2.x 插件选型调研确认，目标实例 Halo 2.26.1 满足 AI Foundation、智阅全能AI助手、MiniDocs、项目集的版本门槛。四者真实插件名为 ai-foundation、summaraidGPT、halo-plugin-minidocs、portfolio；智阅依赖 AI Foundation，MiniDocs、项目集独立。实例已启用 AI Foundation 1.1.0，但仅配 DeepSeek 语言模型，无 Embedding，导致 RAG、向量检索和前台访客问答当前不可用。AI Foundation 只是模型接入与调用底座，不含知识库、分块、向量库和前台页面，搜索仍为 Lucene 关键词。选型应先配语言与 Embedding 模型，再装智阅；版本以 Releases 或市场为准，不能信 plugin.yaml 的 version。

Halo Pro 2.26.1 实例的镜像 tag 2.26 为滚动标签，升级/回滚应锁 digest，镜像回滚不等于数据库回滚。Docker 日志已轮转，halo.log 无轮转，需用 logrotate 的 daily 加 maxsize 20M，避免 size 覆盖 daily；备份改用用户级 crontab，健康检查已启用并修正重启误报。项目集真实路由为 /portfolio，已新增“文档”“项目”菜单及 skills、timeline 页面，清理 7 个主题演示字段；但项目、技能、履历数据仍为空，external-url 实际生效公网域名故未改。前台匿名路径均 200，API 仍需登录。可据此避免版本漂移、日志漏轮转与告警误报。

构建 Docker 镜像须以仓库根目录为上下文，先构建前端产物，否则 go:embed 无法嵌入最新 WebUI。持久化目录须在 VOLUME 前 chown 给 tunnel(10001)，否则日志和备份静默失败；bind mount 需在 Linux 手动 chown。compose 部署已验证健康检查、17 张表、登录与验证码一次性；数据库默认仅绑 127.0.0.1，推荐 SSH 隧道。管理员口令不能只改 .env 重启，需后台修改或删 users 重建。上线清单涵盖部署、验证、安全加固与回滚。

飞牛 OS/Debian 12 的 Halo NAS 脚本提供全量备份、非破坏恢复验证、破坏性恢复、健康检查与定时轮转。备份含数据库、全局角色、halo2、compose/env 和校验清单，只增不改，默认保留 7 份；恢复前先验证，灾难恢复先备份现状，再停 Halo、恢复库和文件。数据库命令须显式走容器内 PostgreSQL，--clean --if-exists 具破坏性。隧道配置上，TUNNELS 仅支持简写且本地地址固定 127.0.0.1，容器须用 TUNNELS_FILE；域名跨客户端占用会被跳过；泛域新隧道云端零改动，改 tunnels.json 重启 tunnel-client，改 client.env 需强制重建容器。

intranet-tunnel 当前只保留服务端 1.1.1、客户端 1.2.1 归档，历史包已清理，旧 docker load 命令会报文件不存在。1.2.1 修复 Web 配置登录后界面无反应，纯客户端，服务端无需升级；1.2.0 新增 Web 配置界面、SQLite 持久化与 init.sh，并修复状态恒为 connecting。Gitea 私有 Release 附件未认证下载返回 404，需带 token 验证。Halo 集成脚本宜跑 NAS，凭据只放 env 且 chmod 600，令牌按最小权限配置，README 默认不搬运，首次默认 draft。

面板自带 DNS-01 有缺陷：把 ACME 授权标识符直接当 DNS 托管主域传给服务商，阿里云报 InvalidDomainName.NoExist，根因是缺少待签域名到托管主域的解析。规避可用 acme.sh 的 dns_ali 做 DNS-01 签发，覆盖 tunnel.sushike.cloud 与 *.t.sushike.cloud，cron 自动续期并触发 nginx 重载，且不要再导入面板以免双重续期。常规申请可在面板选 HTTP-01，需 80 端口公网可达；证书落 ./certs/<域名>/，nginx 已挂载。申请后需 docker compose restart nginx；自动续期后 nginx 不会自动重载，默认仍需手动 restart。

记录在已运行宝塔面板的 Ubuntu 24.04 云服务器（1.5 GiB 内存）上部署 intranet-tunnel 的实测。关键结论：不启 compose 内 nginx，保留宝塔 80/443；改用 *.t.sushike.cloud 避开泛解析和 _acme-challenge 冲突；下调容器内存上限；直接改数据库开启面板外网访问。部署需补挂 certs/backups/logs、chown 10001，证书改用 acme.sh DNS-01 自动续期。新增放行 47800、48081-48100，管理口仅绑本地。最终三容器健康，HTTPS 200、HTTP 301。另含 Workbench CLI 传参、宝塔统计需注册 site.db、nginx 日志三路输出与轮转等踩坑。

部署实测：compose 缺证书与备份挂载，需补齐；绑定目录后须改属主 10001:10001，否则权限报错并无限重启。面板外网访问读 system_settings，需直接改库。阿里云 DNS-01 不可用，改用 acme.sh 避免重复续期。Workbench CLI 误把 - 开头 token 当参数，宜上传脚本执行；upload 有覆盖保护，输出会截断。阿里云 API 签名须按 Ordinal ASCII 排序，否则报不匹配。

隧道客户端验证与排障要点：测隧道域名须解析到公网 IP，勿用 --resolve 指向 127.0.0.1，否则绕过 SNI 返回 404；DNS 缓存会造成新记录未生效假象。确认是否经本方案应看 X-Proxy-By: intranet-tunnel，而非仅看状态码或 Portainer 响应头；更严格可用 SHA256 与后端直连比对，动态页面改比响应头。排查可用 logs、print-config、/healthz；tunnels 含服务端下发，可能多于 tunnels.json，persistence:false 多因 data/ 权限。常见故障涉及 Token、连接/证书、502、env_file 需重建、47802 端口绑定及配置持久化。

边缘配置自动同步让新增隧道域名不再需要手工维护 nginx：泛域内域名共用通配 server 块，新增隧道无需改配置；泛域外自动生成专属 server 块并使用自身证书，使配置规模与隧道数量解耦。服务端只写文件，由容器看门狗或 systemd path unit 校验并 reload，兼容纯 Docker 与宝塔 nginx，宝塔只接管 443 并保留 80 跳转和统计。校验失败会放弃 reload 并把坏配置移出 include 目录，防止后续 nginx 启动失败，故 conf.d 必须可写。证书路径须填 nginx 侧路径，HTTP/2 语法由 EDGE_HTTP2 适配；证书需 DNS-01 申请通配符并自动续期，私钥权限 600 且不入库。