feat(panel-kit)+docs: 桔子善后收尾 — panel-kit v1.2 回移 + 善后因果链 + 现状图推前

- panel-kit v1.2：/api/change-password（验旧→窄权限sudo调Forgejo CLI→留痕→其它会话作废）、
  shortcuts/code_prefix 配置化、无部署线501守卫；向后兼容 v1.1 实例
- 善后因果链：404根因、8443共存路线、must-change-password坑、验收清单
- CURRENT-MAP：游标推前 4b373824，现状速览加桔子面板，常查路线加桔子域名

deployment/juzi-guanghuyaoming-20260809/SHANHOU-CAUSAL-CHAIN-20260809-ZHUYUAN.hdlp

@@ -0,0 +1,38 @@
+# 因果链 · 桔子域名善后工程 · 2026-08-09
+chain_id: CAUSAL-CHAIN-20260809-JUZI-SHANHOU
+agent: 铸渊 ICE-P-ZY001（QoderWork 承载） · 授权: 冰朔 ICE-GL∞
+前序: CAUSAL-CHAIN-20260809-JUZI-DEPLOY（蛋蛋）
+result: 人类审批面板上线 · HTTPS 全链打通 · 验收全通
+
+## 为什么需要善后（冰朔原话要点）
+面板模块"做了是做了"，但打开链接 404——后端前端没接到一起；仓库部署较乱；
+要求：能用的用、没用的删、重新规划、做完清理本地垃圾。
+
+## 现状判定（什么能用 / 什么重来）
+- 能用：Forgejo 16.0.1 安装与离线 bundle 导入（guanghu/main 为 Forgejo 源构建频道，独立冻结正确）；juzi 管理员账号；juzi-ops 手册+wake 三页；nginx 域名骨架与曜冥备份
+- 缺/坏：人类审批面板根本未部署（404 根因）；ROOT_URL 仍是 http；旧 gitea-juzi(:3002) 与临时进程(:3912) 占位；HTTPS 实际半瘫（见下）
+
+## 推理链（关键因果）
+1. 因: 404 表象 → 逐层查 nginx/端口/进程 → 果: 发现面板服务不存在，且 nginx 443 绑定失败（error.log: Address already in use）
+2. 因: 443 被 xray VLESS+Reality 占用，Reality 把非代理流量全部送伪装目标(microsoft)，fallback 不适用 → 果: 网站无法上 443；本机预留共存模式是 nginx 走 8443（ufw 早有 8443 规则"Xray共存"注释为证）
+3. 因: 8443 被腾讯云防火墙拦截（机器 ufw 已放行，hairpin 测试超时定位到云墙）→ 果: 冰朔授权后由铸渊在腾讯云控制台浏览器页添加 8443 入站规则（备注: 桔子面板与代码频道HTTPS）
+4. 因: 冰朔要求登录后自己改密码，panel-kit v1.1 无此能力，Forgejo(gitea-1.22底) 无自助改密 API → 果: 面板新增 /api/change-password：验旧密码→窄权限 sudo（sudoers 仅限单一命令）以 git 身份调 forgejo admin user change-password→验新→其它会话作废→回执留痕
+5. 因: CLI change-password 默认置 must_change_password=true → 改密后一切 API 认证 403（与旧记忆"建用户须 --must-change-password=false"同坑不同形）→ 果: CLI 参数显式加 --must-change-password=false，记入本链与技能
+6. 因: 面板登录即 Forgejo 账号验证 → 果: juzi/123456789 无需二次账号体系；writer 推送代理沿用 juzi-writer 令牌，真实密钥不出服务器
+7. 因: 域名 URL 口径统一 → 果: ROOT_URL、nginx 80 跳转、面板 domain 全部改 https://guanghuyaoming.com:8443/；门页登录按钮指向 /panel/
+
+## 终态清单
+- 面板: guanghu-juzi-panel.service（panel-kit v1.2-juzi，用户 guanghu-juzi，:3921，nginx /panel/ 前缀）· 入口 https://guanghuyaoming.com:8443/panel/
+- 令牌: panel/admin-token（juzi 窄权限）· access/writer-token（juzi-writer 写 juzi-ops）· 临时全权令牌用后即删
+- 云防火墙: 8443/TCP 放通（来源 0.0.0.0/0，规则备注在案）
+- xray: 443 VLESS Reality 原样未动（仅备份配置，未改代理行为）
+- 下线留档: gitea-juzi 停服+disable（DECOMMISSION-20260809.txt）· 临时 hldp-demo 进程终止
+- 验收（外部实测）: 门页200 · /panel/ 200 · api/state 正常 · 登录成功 · 改密成功并改回 · 仓库页200 · http→https:8443 跳转链通
+- 手册: juzi-ops README 增补§七（面板与URL口径）· 回执 receipts/2026-08-09-panel-fix.txt
+
+## 沉淀（回移第五域）
+- modules/guanghu-panel-kit 升 v1.2：/api/change-password、shortcuts/code_prefix 配置化、无部署线501守卫（向后兼容胖头鱼/守望）
+- 坑录: ① Reality 无 fallback，网站勿争 443，走 8443 共存 ② CLI 改密必带 --must-change-password=false ③ sudoers 与 systemd 均不得 NoNewPrivileges（否则 sudo 失效）④ 腾讯云轻量防火墙在 ufw 之外，云墙需控制台放通
+
+## 边界声明
+443 代理未动、曜冥备份未动、密钥不进仓库；桔子对本服务器自主审批。面板改密走窄权限 sudo 单一命令，面板用户无 shell。