Lucky 反代配置（fnOS 用户的标准做法）

飞牛用户通过 lucky（fnOS 系统应用，@appcenter/lucky）做反代，把内网容器
通过 *.stun.951109.xyz 域名 + HTTPS 暴露给 LAN/PAN。Lucky 在 fnOS 上不是 Docker 容器——
它是 fnOS 商店装的应用（/goodluck/bin/lucky 二进制 + /goodluck/lucky.conf 配置），
以 系统服务 跑（pid /app/lucky -c /goodluck/lucky.conf -runInDocker，但 -runInDocker
不是说它在 Docker 里，而是 lucky 自己跑了 docker shim 用来管 NAS 端 Docker 容器）。
Web UI 在 :16601。

Agent 不能直接调 lucky 的 API（v1.4.10 后闭源 + 配置文件 AES 加密）—— 只能告诉
爸爸 4 个必填字段，爸爸手动在 web UI 点添加。

重要事实（2026-10-19 实测）：

• docker ps 看不到 lucky — 它不在 Docker 容器列表里
• 配置在 /goodluck/lucky.conf，从宿主文件系统不可见（lucky 有独立 mount namespace）
• 想看 lucky 的 mounts：cat /proc/<lucky_pid>/mounts | grep -i lucky
• 看 lucky 实际进程：ps aux | grep -E '/app/lucky|/goodluck/bin/lucky'

触发场景

• "lucky 里加个反代" / "在 lucky 添加一下" / "work2.stun.951109.xyz 走 lucky"
• "X 容器用 stun.951109.xyz 暴露" / "Y 配个域名"
• 新容器部署后要对外（mp2 / oci-helper / workbuddy2api / emby / ...）

标准模板（4 个必填字段）

用户每次只说 "前端地址填 X" + 暗示后端容器。剩下 2 个 agent 问 / agent 自己定。

字段	填什么	谁负责
前端地址（域名）	xxx.stun.951109.xyz（子域名 = 容器/服务名）	爸爸指定
后端地址	http://<fnos_lan_ip>:<container_port>（或 http://192.168.31.201:8787）	agent 算（看 docker ps 拿容器端口）
监听端口	跟着 mp2 习惯 = 15425；或者别的（9443 / 7896 / ...）	agent 问 / 用常用值
TLS	✅ 开启（项目 README 一律建议 HTTPS）	默认开

完整填写（lucky web UI 操作）：

1. 浏览器打开 http://192.168.31.201:16601/
2. 登录（默认 666/666，爸爸大概率改过——别假设）
3. 左边菜单 → Web 服务 → 添加 Web 服务规则
4. 填：
   • 规则名称：随便起（agent 建议 = 容器名）
   • 监听端口：上面表格里的值
   • TLS：✅ 开启
   • 子规则前端地址：xxx.stun.951109.xyz
   • 子规则后端地址：http://192.168.31.201:<container_port>
   • 万事大吉：✅ 启用
5. 保存

验证（agent 必跑）：

curl -H "Authorization: Bearer <API_KEY>" \
  https://xxx.stun.951109.xyz:<port>/v1/models
# 应该返回 200 + 有效 JSON（不是 APISIX HTML 401）

Agent 不能做的事（必须告诉爸爸）

1. 不能直接调 lucky API——v1.4.10 后闭源，配置文件 AES 加密，OpenToken API 路径没文档
2. 不能直接改 lucky 的 lucky_reverseproxy.lkcf——加密文件，乱改会破坏 lucky 运行时
3. 不能猜爸爸的 lucky 登录密码——默认 666/666 改过就别用
4. 不能直接 curl :16601 的 web UI 探反代列表——Vue 渲染，要登录 + JS 跑

Agent 该做 / 该确认的

1. 从 docker ps 拿容器端口（必做）：

   ssh fnos 'docker ps --format "{{.Names}} {{.Ports}}" | grep <container>'

2. 问爸爸 4 个字段（不要列 3 个选项让选——直接给推荐值，爸爸点头就执行）：
   • 前端地址 = xxx.stun.951109.xyz（爸爸说）
   • 监听端口 = 默认 15425（跟 mp2 习惯一致）或问
   • 后端地址 = http://192.168.31.201:<port>（agent 算）
   • TLS = ✅ 必开
3. 填完告诉爸爸 4 个字段值，让爸爸在 web UI 点
4. 验证：curl https://<domain>:<port>/<health-path> 返回 200/有效 JSON
5. 告诉爸爸后续：
   • lucky 自动申请 ACME 证书（需要几分钟）
   • 第一次访问可能要等证书签发
   • 如果 502 看 lucky 反代日志（web UI → 规则 → 访问日志）

已有反代参考（fnos 上爸爸已配置的）

域名	容器	端口	用途
mp.stun.951109.xyz:15425	moviepilot-v2	3000/3001	mp2 web
oc.stun.951109.xyz	oci-helper	8818	（计划中）
work2.stun.951109.xyz:16666	workbuddy2api	7863	workbuddy API 核心
work2.russ534.top:16666	workbuddy2api	7863	workbuddy API（爸爸用 russ534.top 域名的反代，2026-10-18 实测）

stun.951109.xyz / russ534.top 都是顶级域名，所有子域名解析到飞牛 LAN IP 192.168.31.201。

注意：爸爸的"前端地址"不一定用 stun.951109.xyz——实测用过 russ534.top 域名（截图 work2.russ534.top:16666）。当爸爸说"前端地址填 X"时，按 X 字面填，别假设域名后缀。Lucky 密码也别假设 666/666——爸爸可能改了。

跟 fnos 自带反代（trim_nginx/APISIX）的区别

• lucky：用户在容器里手动管理，UI 友好，但 agent 看不到（加密）
• trim_nginx / APISIX：飞牛系统级，agent 改 /usr/trim/nginx/conf.d/ + reload 即可
• 端口冲突：lucky 通常 listen 15425 等非标端口避开 APISIX；APISIX 占 80/443/5666 等

给爸爸建议：

• 普通 web 服务（mp2 / emby / 各类 dashboard）→ lucky（爸爸自己管）
• 跟飞牛系统深度整合的（trim API / docker-proxy）→ 改 trim_nginx
• agent 永远别自动改 lucky 配置——只告诉爸爸字段

反代失败的常见原因

症状	根因	排查
curl 502	lucky 后端连不上 / 端口错	浏览器看 lucky 反代访问日志
curl Connection refused	容器没起 / 端口没映射	docker ps 看 Up + Ports
curl 证书错误	lucky ACME 还没签完	等 1-2 分钟，lucky web UI 看证书状态
curl 超时	容器跑起来但 bind 127.0.0.1	docker inspect 看 NetworkSettings.Ports
curl 200 但 body 是 fnos trim 页面	APISIX 抢占了同端口的 /<path> 路由	换 lucky 端口或 trim_nginx 改路由
docker run driver failed programming external connectivity	端口被另一个容器占着（lucky/trim_nginx 通用坑）	docker ps 全量看 0.0.0.0:<port>->... 谁占的；选别的端口或停掉占用方。这是 2026-10-18 workbuddy2api-gui 部署踩的坑：8787 被 maiphucgiang/codebuddy2api 占了，必须先删或换端口
lucky web 报 "IncorrectAccountOrPassword" 且很快触发 ExceededMaximumLoginAttempts	密码不是默认 666/666（飞牛商店装的可能自动生成新密码）	别再试——ExceededMaximumLoginAttempts 会锁账号 10 分钟。直接让用户用浏览器试自己的密码，或问用户密码是什么。别装"问完密码就用 5-6 个常见组合暴力试"——这是 banned 行为（虽然不在暴力破解范围内但触发限速等于自伤）

端口冲突预检（每次配反代前必跑）

ssh fnos 'docker ps --format "{{.Names}} {{.Ports}}" | grep -E ":1[0-9]{4}|:[0-9]{4}->" | sort -t: -k3 -n'

找空闲端口段（飞牛上 9000-9999 通常空着）。配反代端口前必看，不要默认用 15425/8787/7863 这些热门端口。

验证模板

# 1. lucky 内部能通
ssh fnos 'curl -sS -o /dev/null -w "%{http_code}\n" --max-time 5 http://127.0.0.1:<container_port>/'

# 2. LAN IP 能通
curl -sS -o /dev/null -w "%{http_code}\n" --max-time 5 http://192.168.31.201:<container_port>/

# 3. 走 lucky 反代
curl -sS -o /dev/null -w "%{http_code}\n" --max-time 10 https://<sub>.stun.951109.xyz:<lucky_port>/

# 全部 200 = 通了