俗世客的思行小筑

MiniDocs 批量导入本地 Markdown 可行但边界明确：minidocs-cli 已验证；API multipart 字段与 CRUD 只写 raw 是否致空白未确认；自制 ZIP 不可行，仅支持插件导出 ZIP。导入前知识库须存在，文档默认草稿需发布，CLI 需 PAT。上架应保持 docsme 禁用避免 /docs/* 冲突，本实例主题模板安全；目录折叠未实现，2.26.1 兼容性未专项确认。前台与分享未验证；本次仅建结构，未填正文，未启用批量导入。

数据库外访默认仅绑定本机回环，局域网和公网不可直连；开放须同时改 compose 绑定并放行防火墙，更推荐 SSH 隧道，注释映射不影响服务端。备份链路已跑通且可恢复，建议装 cron，日志轮转用 maxsize；宿主另有 PostgreSQL，DB 操作走 docker exec。镜像须在 VOLUME 前创建并 chown 数据、日志、备份、证书目录，否则文件日志和备份静默失败；bind mount 需将宿主目录权限改为 10001。发现端口暴露、角色权限过高、私钥可读与口令明文等风险，需收敛暴露与权限。

排障隧道时容易自设陷阱。curl --resolve 指到 127.0.0.1 会绕过公网入口 SNI 并实测 404，应解析到公网 IP；DNS 缓存会让新增 *.tunnel 记录看似未生效，本机仍解析旧阿里云 IP 并返回他站内容，需等缓存过期或强制解析。Portainer CE 响应头易误认成企业站，判断隧道生效应看 X-Proxy-By: intranet-tunnel 或 HTML 中的 Portainer 标识。此外，EnsureTunnelRule/RemoveTunnelRule 无调用点，隧道变更后反代规则不自动更新，访问域名返回内置反代 404，启动日志 rules=0 tunnel_rules=N 可判断；临时调用重载接口或重启 tunnel-server，根治需在 control 包变更处调用。

服务端可调 API 脚本化检查：先验 /healthz 和公开配置，登录后查 20 项端点；密码从容器环境变量取，勿写脚本。using_default_credentials 只判断用户名是否为 admin，并非弱口令。凭据失效先查审计日志中的 token/password 重置；ERROR 日志按时间戳判断是否历史遗留；关验证码需备份恢复。服务器无源码，镜像更新走本地构建、save、上传、load、改 tag、up -d，保留旧 tag 可回滚。DSH 会话记录可恢复源码，zstd 需逐帧解压，只重放成功操作，防重复与 BOM 问题。

双会话并行提交时，各自只暂存本目录文件，提交前核对暂存区；提交信息文件放仓库外，多行用 -F，禁用 git commit -a，index.lock 冲突重试不删锁。源码由 git 保护，提交钩子自动推送到本地裸仓库和 NAS 私有 Gitea，改完应尽快提交。.env 及凭据不入库，只更新脱敏示例；release 包不入库，frontend/dist 保留 gitkeep。内网 Gitea 需绕过系统代理，发布附件用 Node 脚本而非 curl.exe。

服务端 v1.0.6 已上线，移动端接口契约冻结。App 必须适配 2FA：开启后 /api/mobile/auth/login 返回 mfa_required 与 mfa_ticket 而非令牌，须再调 2fa/verify，否则会把质询误存为会话。新增告警中心，支持列表、详情、已读/处置与未读计数，暂无系统推送；移动端分页接口、公网地址用 entry，登录字段名为 token，勿向既有接口附加字段。真实联调需本地实例。portfolio 插件实测 API 非 REST，写操作用 create/update 且按 slug 定位，platform/type 须用选项 value，Markdown 表格不渲染。

内网穿透控制台 Web 端在 feature/ui-refactor 分支完成 UI 现代化、暗色主题、图形/短信验证码登录，新增设计令牌、通用组件与短信表结构；既有业务接口、路由、鉴权、store 语义保持兼容，支持回滚，TS/Pinia 迁移仅给出后续路径。移动端基于 uni-app/Vue3，已完成登录鉴权、仪表盘、列表详情、告警中心和轻操作，聚焦查看、轻操作与告警，阶段六待开始，令牌存储三级降级。选型推荐 uni-app，若推送或原生能力为硬指标则考虑 Flutter；Android 打包推荐 HBuilderX 命令行云打包。

Intranet Tunnel 本轮修复了 2FA、并发写库和审计发现的问题。2FA 原先设置可开但登录不校验，v1.0.6 在登录前插入第二因子，票据改为内存一次性、带 TTL，并防 TOTP 重放；丢失认证器只能改库并重启恢复。v1.0.7 解决并发写导致的 500：SQLite 因 DEFERRED 锁升级报 SQLITE_BUSY，改用 immediate 事务与 10 秒 busy_timeout；PostgreSQL 因设置项 map 遍历顺序随机而死锁，落库前按 key 排序。安全审计中 19 项功能用例未发现可利用漏洞，8 项 DDoS 攻击均被防护，修复 JWT 默认密钥、协议帧内存放大等 4 个缺陷；残余风险为隧道 local_addr SSRF、NAT 限流失效和带宽型攻击。

Halo 备份须三层齐备：数据库 pg_dump、halo2 文件、compose/env 配置，缺一难恢复；插件、主题、keys 不在库中，keys 丢失 PAT 失效。默认不停机，库与文件非同一时间点，窗口不足 6 秒，目前无附件。演练约 5.5 秒完成，sha256 校验通过；恢复验证用临时库，生产库未写入，以表数 34、extensions 行 391 相等为判据，不能只看 pg_restore 无报错。恢复生产要先备份现状、停 Halo、恢复库和文件、起服务并健康检查。最大缺口是备份与生产同卷、无异地副本。运维每日查健康与备份新鲜度，每周恢复验证和校验，每月异地副本、完整演练、digest 与权限复核，匿名用户接口必须 302。

Halo 站点知识库设计分类与标签：分类按工作线划分，一级8个、二级20个，最长3级，每篇1个主分类；标签小写单数短横线，首批45个，单篇2~5个，全站上限50。实测20个二级分类为空且与一级平铺，前台曾列29个分类入口、28个空页，现全部隐藏，入口降至9个，首篇文章后恢复。分类与标签同slug可共存，显示名不得重复；3组完全同名分类已改显示名，未删分类标签，slug和旧链接不变。另建38节点知识库树，7顶级、3层，先占位发布。