下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/user_d6a594cc--nas-remote-control.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_d6a594cc/nas-remote-control。让手机 / 云端 AI(没有 SSH、没有内网、没有厂商 CLI)远程指挥一台家里的 NAS 或 Linux 主机——在目标机上常驻一个 Token 鉴权的 HTTP 白名单服务(nas-guard),再用 Tailscale Funnel 开一条公网 HTTPS 入口。含现成的服务端脚本、手机网页遥控台、部署脚本、以及 Tailscale Funnel 的完整踩坑清单。
触发词:手机遥控NAS、云端AI管NAS、远程控制飞牛、公网访问家庭服务、Tailscale Funnel、serve.json、AllowFunnel、nas-guard、手机控制家里的服务器。
阅读全文 (展开查看完整说明)
概述
nas-remote-control —— 手机 / 云端 AI 远程遥控 NAS
这个技能解决什么问题
场景:你在外面,想用手机(或手机上的 AI 助手)指挥家里的 NAS 干活——查容器状态、拉日志、加首歌、整理文件。但:
- 手机 AI 跑在云上,进不了你家内网;
- NAS 厂商的 CLI(如飞牛
trim-cli)是 Windows 专有二进制 + 令牌存在本机,云端根本没法用; - 家庭宽带没有公网 IP,端口转发行不通;
- 内网穿透(frp)需要另一台有公网 IP 的服务器,运维成本高。
解法(本技能)分两步:
手机 / 云端 AI
│ HTTPS + Token
▼
┌─────────────────────────┐
│ Tailscale Funnel │ ← 第 2 步:公网入口(自动签 Let's Encrypt 证书)
│ https://xxx.ts.net │
└───────────┬─────────────┘
│ 转发到 127.0.0.1:8099
▼
┌─────────────────────────┐
│ nas-guard │ ← 第 1 步:NAS 上的常驻 HTTP 服务
│ 18 个白名单动作 + Token │ 只做被允许的事,越界直接拒
└───────────┬─────────────┘
│
┌───────┼────────┬──────────┐
▼ ▼ ▼ ▼
文件系统 音乐库 Docker 系统信息特点:
- 目标机侧只要一个容器,纯 Python 标准库,没有第三方依赖;
- 调用方(云端 AI / 手机浏览器 / curl)只需要一条 HTTP 请求;
- 与"家里电脑开不开机"完全解耦。
何时用
- 用户说"我在外面想用手机管 NAS"、"让手机上的 AI 直接操作我家的服务器"
- 需要一个公网可达的、有鉴权的、能力受限的远程管理入口
- 已经有一个家庭服务(下载器 WebUI、Home Assistant、自建 API),想安全地暴露给手机或云端
- 正在折腾 Tailscale Funnel 但卡住了(见
reference/tailscale-funnel-pitfalls.md)
不适用:
- 目标机本来就是公网 VPS → 直接开端口 + nginx + 鉴权即可,不需要 Funnel
- 只想让自己的手机访问(不需要 AI)→ 用厂商自带的远程访问(如飞牛的 FN Connect 应用代理)+ 手机浏览器就够了,见下文「方案 B」
三套方案,按需选
| 方案 | 前提 | 谁能用 | 成本 |
|---|---|---|---|
| A. 只给自己手机用 | 厂商有远程访问功能 | 人(浏览器) | 零成本,但机器/AI 用不了 |
| B. nas-guard + Tailscale Funnel | 一个 Tailscale 账号(免费版够) | 人 + 机器 + AI | 推荐 |
| C. nas-guard + Cloudflare Tunnel | 一个域名 + Cloudflare 账号 | 人 + 机器 + AI | 备选,见 reference/alternatives.md |
⚠️ 方案 A 的天花板:飞牛的 FN Connect 应用代理(
https://<容器ID前12位>-0.<域名>)由飞牛账号登录态鉴权,没有登录态一律 403。人用手机浏览器很方便,
但云端 AI / 脚本 / 沙箱拿不到那个登录态,所以"让 AI 管 NAS"必须走方案 B。
方案 B 实施(推荐路径)
第 0 步:前置检查
在目标 NAS 上确认:
# 1. 有没有 Docker(nas-guard 跑在容器里)
docker version
# 2. 能不能出外网(Tailscale 要连协调服务器)
docker run --rm alpine:latest wget -qO- -T5 https://login.tailscale.com >/dev/null && echo NET_OK
# 3. 目标服务的端口(示例是音乐库下载器 8088)
curl -s -o /dev/null -w '%{http_code}n' http://127.0.0.1:8088/第 1 步:部署 nas-guard
① 建目录、放文件、生成 Token
把 bin/guard_server.py 传到目标机(例如 /opt/nas-guard/),然后生成配置文件:
# 在目标机 NAS 上
python3 bin/deploy_nas_guard.py --dir /opt/nas-guard --data /mnt/data --music /mnt/music或者手动(等价):
mkdir -p /opt/nas-guard
cp guard_server.py /opt/nas-guard/
python3 -c "
import json,secrets
json.dump({'token':secrets.token_hex(16),'port':8080,'readonly':False,
'subfolder':True}, open('/opt/nas-guard/config.json','w'))
"
cat /opt/nas-guard/config.json # ★ 记下这里的 token,后面每一步都要用② 起容器
docker run -d --name nas-guard --restart=always
--memory 128m
-p 8099:8080
-v /opt/nas-guard:/app
-v /mnt/data:/data
-v /mnt/music:/music
-v /var/run/docker.sock:/var/run/docker.sock
-e MUSIC_DL_BASE=http://172.17.0.1:8088/music
python:3.11-alpine
python3 /app/guard_server.py★ 挂
/var/run/docker.sock是必须的:nas-guard 用它读容器日志、启停容器。这也意味着 nas-guard 权限很高——所以它的 Token 必须当密码保管。
③ 自检
TOKEN=$(python3 -c "import json;print(json.load(open('/opt/nas-guard/config.json'))['token'])")
curl -s -H "X-Token: $TOKEN" http://127.0.0.1:8099/health
# 期望:{"ok": true, "ts": ..., "service": "nas-guard", "readonly": false}
curl -s -o /dev/null -w '%{http_code}n' http://127.0.0.1:8099/health
# 期望:401(没带 Token 必须被拦)
curl -s -o /dev/null -w '%{http_code}n' http://127.0.0.1:8099/
# 期望:200(网页遥控台,页面本身不需要 Token)④ 手机在同一 WiFi 下先试用
浏览器打开 http://<NAS内网IP>:8099,粘贴 Token,点几个按钮。这一步过了再去做第 2 步——否则公网开了也白开。
第 2 步:开公网入口(Tailscale Funnel)
详细踩坑过程见
reference/tailscale-funnel-pitfalls.md。这里有两个能让任何人卡一整天的坑,已用 ★★ 标出。
① 起 Tailscale 容器
docker run -d --name tailscale --restart=always --memory 128m
-p 41641:41641/udp
-v /opt/tailscale:/state
-e TS_USERSPACE=true
-e TS_STATE_DIR=/state
-e TS_SOCKET=/state/tailscaled.sock
-e TS_HOSTNAME=my-nas
-e TS_ACCEPT_DNS=false
-e TS_AUTH_ONCE=true
-e TS_BOOT_TIMEOUT=720h
-e TS_SERVE_CONFIG=/state/serve.json
tailscale/tailscale:latest⚠️
TS_USERSPACE=true:在 NAS 上给容器/dev/net/tun常有限制(飞牛的 trim-cli 就给不了),用不了内核态组网就只能用户态(
tailscaled+ 用户态网络栈),功能上够用。如果是标准
docker run且宿主机内核允许,也可以改用--cap-add=NET_ADMIN --device /dev/net/tun+TS_USERSPACE=false(性能更好)。
★★ 坑 1:
TS_BOOT_TIMEOUT=720h不设,登录态永远存不下来。
containerboot这个 wrapper 对整个引导过程有一个默认 60 秒的硬超时(bootCtx)。未登录时
tailscale up要等协调服务器回 map 响应,60 秒等不到就报
failed to auth tailscale: ... context deadline exceeded→ 进程退出 →
--restart=always把它拉起来 → 每次重启都生成一个新的 nodekey →你刚在浏览器点过的授权链接立刻作废。症状:
容器状态永远是
Up N seconds(而不是Up 45 hours),
tailscaled.state永远只有 ~119 字节(只剩_machinekey)。注意:
TS_EXTRA_ARGS=--timeout=720h没用——那是tailscaleCLI 自己的超时参数,管不到 containerboot 的
bootCtx。必须是TS_BOOT_TIMEOUT。配合
TS_AUTH_ONCE=true(已登录就不再强制重登)。
② 首次登录(人来做)
docker logs tailscale 2>&1 | grep -A2 'AuthURL is'
# 把 https://login.tailscale.com/a/xxxxx 交给用户,在浏览器打开并授权授权成功后日志会出现 Success.,/state/tailscaled.state 会长到几 KB。如果 state 一直是 119 字节,就是坑 1 没处理,回去补 env 并重建容器。
③ Tailscale 管理后台开两项开关(人来做)
在 https://login.tailscale.com/admin/dns:
- ✅ MagicDNS
- ✅ HTTPS Certificates
④ ACL 放行 funnel(人来做)
在 https://login.tailscale.com/admin/acls 的策略文件里,把 nodeAttrs 加在最外层(新版策略用的是 grants 语法,nodeAttrs 和 grants 平级):
{
// ... 你原有的 "grants": [ ... ],
"nodeAttrs": [
{ "target": ["autogroup:member"], "attr": ["funnel"] }
]
}点 Preview changes 看没报错再 Save。
⑤ 写 serve.json 并启用 Funnel
先拿到真实的 DNS 后缀(★ 不是后台显示的那个 tailnet 名字):
docker logs tailscale 2>&1 | grep -i 'for:' | tail -3
# 期望看到类似:Fetching TLS certificate via ACME for: my-nas.tailxxxxx.ts.net
# 这里的 my-nas.tailxxxxx.ts.net 才是真域名然后写 /opt/tailscale/serve.json:
{
"TCP": { "443": { "HTTPS": true } },
"Web": {
"my-nas.tailxxxxx.ts.net:443": {
"Handlers": { "/": { "Proxy": "http://127.0.0.1:8099" } }
}
},
"AllowFunnel": { "my-nas.tailxxxxx.ts.net:443": true }
}★★ 坑 2:
AllowFunnel必须是ServeConfig的顶层字段。它是一个
map["host:port"]bool,不在Web条目里面。放在
Web里会被静默丢弃(解析器不认识的字段直接忽略,不报错),结果是
tailscale funnel status永远显示(tailnet only)(只是 tailnet 内可见),日志里能看到 ACME 退化成 dns-01 并报
Funnel is not enabled for my-nas.tailxxxxx.ts.net:443。这个坑没有任何报错信息指向真正的原因,只能去读 Tailscale 源码
ipn/serve.go才定位到。
改完 serve.json 后重建容器(containerboot 会监听文件变化重载,但存在"读到半截/空文件就 skip"的竞态,重建最稳):
docker restart tailscale⑥ 验证
# 容器内视角(最权威)
docker exec tailscale tailscale --socket=/state/tailscaled.sock funnel status
# 期望看到 (Funnel on) 和你的域名:443
docker exec tailscale tailscale --socket=/state/tailscaled.sock serve status --json
# 期望 JSON 里 AllowFunnel 有你的域名:443 -> true
# 公网视角
TOKEN=你第1步记下的token
curl -s -o /dev/null -w '%{http_code}n' https://my-nas.tailxxxxx.ts.net/health
# 期望 401(没 token)
curl -s -H "X-Token: $TOKEN" https://my-nas.tailxxxxx.ts.net/health
# 期望 200 + {"ok": true, ...}⚠️ 如果本机 curl 报"Could not resolve host":多半是你所在网络的 DNS
解析不了
*.ts.net(部分家用路由/运营商 DNS 会过滤)。用公共 DNS 验证一下,或直接指定 IP:
nslookup my-nas.tailxxxxx.ts.net 1.1.1.1 # 拿到 A 记录 IP curl --resolve my-nas.tailxxxxx.ts.net:443:<上一步拿到的IP> -H "X-Token: $TOKEN" https://my-nas.tailxxxxx.ts.net/health这不是 Funnel 的问题,云端(用公共 DNS)不受影响。家里设备直接用内网地址即可。
第 3 步:把入口交给手机 / 云端 AI
把下面这段(替换成你的真实地址和 Token)作为第一条消息发给手机或云端的 AI:
你现在的任务:通过 HTTP 遥控我的 NAS。你没有 SSH,也没有厂商 CLI,
只能调用下面这个常驻服务,请严格按说明操作,不要尝试其它方式访问 NAS。
【服务地址】
https://my-nas.tailxxxxx.ts.net
所有请求都必须带请求头:X-Token: <你的 TOKEN>
(也支持把 token 放在网址参数里:?token=<你的 TOKEN>)
【调用方式】
全部是 GET 请求,网址路径就是"动作名",参数放网址后面。例如:
- 查健康:/health
- 容器状态:/docker/ps
- 加歌:/music/add?q=起风了&artist=买辣椒也用券
【可用动作】
- /health 健康检查
- /sys.info 开机时长/负载/内存/磁盘
- /music/search?q=&artist= 只搜索不下载,返回候选和评分
- /music/add?q=&artist= 搜索并择优下载进曲库
- /music/addbatch?q= 批量加歌,每行「歌名|歌手」,≤10 首,异步
- /jobs?id=任务号 查批量任务进度;不带 id 列最近 10 个
- /music/stats 曲库统计
- /music/list?artist=&limit=&offset= 按歌手列歌
- /file/ls?p=/data 列目录
- /file/find?p=&kw=&audio=1 按关键词搜文件名
- /file/mv?src=&dst= 移动 / 改名
- /file/mkdir?p= 建目录
- /file/rm?p= 删除(是移到回收站,不是真删,可恢复)
- /docker/ps 列出所有容器及运行状态
- /docker/logs?name=容器名&tail=50 读容器日志(排查崩溃用)
- /docker/restart|stop|start?name=容器名
【路径规则】
只允许访问白名单根目录,越界会被拒绝;容器操作不允许动 nas-guard 自己。
【工作方式要求】
1. 每次调用后先看 HTTP 状态码再决定下一步:
200=成功;401=Token 错;404=动作名写错;422=动作执行失败;400=参数或路径越界。
2. 失败时把返回 JSON 里的 error 字段原样告诉我,不要自己编一个原因。
3. 需要我确认的动作(删除、移动、停止/重启容器),先说清要做什么,等我同意再执行。
4. 回答用中文,简洁;不要贴大段原始 JSON,挑关键字段说。
5. 如果连不上,直接说"连不上 NAS",不要反复重试。安全清单(上线前逐条过)
这个服务一旦公开,Token 就是你家 NAS 的钥匙。务必做到:
| 项 | 要求 |
|---|---|
| Token 长度 | ≥ 32 位随机十六进制(secrets.token_hex(16))。绝不要用 123456 这类 |
| Token 保管 | 只在私聊/私人笔记里传;不要发到群里、不要贴进论坛、不要截图 |
| 怀疑泄露 | 改 config.json 的 token → docker restart nas-guard(旧 Token 立刻失效) |
| 先只读跑一段 | config.json 里 "readonly": true 可以一键锁死所有写操作(移动/删除/改容器) |
| 删除是软删 | /file.rm 只移到 _回收站/,不是真删——出事了能捞回来 |
| 路径白名单 | safe_path() 只放行配置的两个根目录,用 realpath 防 ../ 穿越 |
| 不许自杀 | docker_action() 硬编码拒绝对 nas-guard 自己执行 restart/stop |
| 暴露面 | Funnel 只开一个端口,Funnel 之外的服务(内含无鉴权的 WebUI)不要一起暴露 |
⚠️ 强烈建议:Funnel 只指向 nas-guard,不要把 qBittorrent / Emby / Home Assistant
这些本身没有强鉴权的 WebUI 直接挂上去。要让 AI 操作它们,就在 nas-guard 里加一个受控动作
(带白名单参数),而不是把整个界面暴露出去。
动作速查
全部是 GET,路径里的 / 等价于服务端的 .(/docker/ps → action docker.ps)。
| 动作 | 参数 | 说明 |
|---|---|---|
health | — | 健康检查,返回 readonly 状态 |
sys.info | — | 开机时长、负载、内存、白名单目录磁盘占用 |
music.search | q artist source | 只搜索,返回候选与评分 |
music.add | q artist source | 搜索并择优下载 |
music.addbatch | q source | 批量加歌,异步,≤10 首 |
jobs | id | 批量任务进度;不传 id 列最近 10 个 |
music.stats | — | 曲库统计(首数/体积/分组排行) |
music.list | artist limit offset | 按歌手列歌 |
file.ls | p | 列目录 |
file.find | p kw limit audio | 按关键词搜文件 |
file.mv | src dst | 移动 / 改名 |
file.mkdir | p | 建目录 |
file.rm | p | 移到回收站,不是真删 |
docker.ps | — | 全部容器及状态 |
docker.logs | name tail | 读容器日志 |
docker.restart / stop / start | name | 控制容器 |
状态码:200 成功 / 401 Token 错 / 404 动作名错 / 422 动作执行失败 / 400 参数或路径越界 / 500 服务端异常。
改 nas-guard 代码后怎么上线
挂载的是目录,不用重建容器:
# 改本地的 guard_server.py → 传到 NAS → 重启容器
docker cp guard_server.py nas-guard:/app/guard_server.py
docker restart nas-guard
docker logs --tail 20 nas-guard # 看启动日志确认没语法错误⚠️ 重启之后立刻
curl -H "X-Token: $TOKEN" http://127.0.0.1:8099/health验一下,别等发现"AI 说连不上"才回头查。
参考资料
| 文件 | 内容 |
|---|---|
reference/tailscale-funnel-pitfalls.md | Funnel 全部踩坑详录(含源码级定位过程、诊断命令) |
reference/alternatives.md | Cloudflare Tunnel / 厂商自带远程访问 / frp 的对比与取舍 |
bin/guard_server.py | 服务端本体(单文件,纯标准库) |
bin/deploy_nas_guard.py | 部署辅助:建目录、生成 Token、打印 docker 命令 |
bin/guard_client.py | 命令行客户端(含 Git Bash 路径转义兜底) |
bin/guard_diagnose.py | 排障:Token / 状态码 / 域名解析 / Funnel 状态一把梭 |
排错
| 现象 | 原因 | 怎么办 |
|---|---|---|
401 bad_token | Token 错/漏填 | 检查 X-Token 头或 ?token= 参数;注意有没有多余空格 |
404 unknown_action | 动作名写错 | 对照速查表;注意末尾斜杠可省,/docker/ps/ 也 OK(服务端会 rstrip('/')) |
404 且动作名看起来像 Windows 路径 | Git Bash 把 /health 转成了 C:/.../PortableGit/.../health | 在 Git Bash 里敲命令时加 export MSYS_NO_PATHCONV=1,或用 guard_client.py health(无前导斜杠) |
422 | 动作执行失败 | 看返回 JSON 的 error 字段(如 no_result、all_tried_failed) |
400 path outside allowed roots | 路径越界 | 只能用 config.json 里配的那两个根目录 |
| 网页遥控台打不开 | 直接访问了公网域名但没 Token | 页面本身免 Token,能开就说明网络通;打不开是网络/DNS 问题 |
| 公网域名解析不了 | 本机 DNS 过滤了 *.ts.net | 换网络,或用 --resolve 指定 IP 验证;见第 2 步 ⑥ |
tailscale 容器一直 Up N seconds | 崩溃循环 = 坑 1 | 补 TS_BOOT_TIMEOUT=720h + TS_AUTH_ONCE=true,重建容器 |
tailscaled.state 只有 119 字节 | 从没登录成功 | 同上;登录成功后会长到几 KB |
funnel status 显示 (tailnet only) | 坑 2 或 ACL 没放行 | 检查 AllowFunnel 是否在顶层;检查 ACL 里的 nodeAttrs |
日志报 Funnel is not enabled for xxx:443 | ACL 缺 funnel nodeAttr | 见第 2 步 ④ |
all_tried_failed 但 inspect 显示有链接 | 平台要 Cookie / VIP | music-dl 免费无 Cookie 只给 mp3;要更高音质得填平台 Cookie |