---
name: fnos-nas
description: >-
  通过外网或局域网操作用户飞牛 NAS（nas.xinhaiblog.top / 192.168.1.13）：文件、Docker、
  应用、监控、下载等。用户提到 NAS、飞牛、fnOS、xinhaiblog、外网操作 NAS、远程管理 NAS，
  或要求 AI 在非局域网环境管理该设备时使用。依赖 fnos-cli；优先走 ~/.local/bin/fnos 自动选路。
---

# 心海飞牛 NAS（外网可操作）

本 Skill 绑定用户自建飞牛设备，让 **能跑 shell 且能访问公网** 的 AI Agent（本机 Cursor、云端 Agent、装了本 Skill 的其它机器）通过 HTTPS 操作 NAS，不依赖必须在局域网。

## 选路原则（必须遵守）

**在局域网内时，一律优先局域网；Cloudflare 外网只作外出兜底。**

| 场景 | 怎么走 |
|------|--------|
| 本机/Agent 能 ping 通 `192.168.1.13` | **强制 LAN**：大文件上传下载、Docker 镜像/二进制、备份、rclone 配置同步、日常文件读写 |
| 仅外出、无局域网 | 再用 CF 域名（`nas.xinhaiblog.top` 等） |
| 给用户看的服务地址 | 同时在局域网时 **先报 LAN URL**，公网作补充 |

原因：经 Cloudflare Tunnel 传大文件会明显变慢；面板遥控可以走 CF，搬砖走 LAN。

Agent 操作约定：

1. 先探测 LAN（例如 `curl -m 2 http://192.168.1.13:5666/` 或 `fnos` 自动选路）。
2. 能通则用 `FNOS_FORCE=lan` / `--profile nas-lan --host 192.168.1.13 --port 5666 --scheme http --allow-insecure-http`。
3. 大文件上传下载 **禁止** 无故走 WAN。
4. 只有 LAN 不通时才 fallback WAN。

## 连接目标

| 场景 | 入口 | 说明 |
|------|------|------|
| 自动 | `$HOME/.local/bin/fnos <cmd...>` | 能通局域网则 LAN，否则 WAN；LAN 失败会 fallback WAN |
| 强制外网 | `FNOS_FORCE=wan $HOME/.local/bin/fnos <cmd...>` | `nas.xinhaiblog.top:443` HTTPS，profile `nas` |
| 强制局域网 | `FNOS_FORCE=lan $HOME/.local/bin/fnos <cmd...>` | `192.168.1.13:5666` HTTP，profile `nas-lan` |
| 原生 CLI | `$HOME/.cursor/skills/fnos-cli/scripts/fnos-cli` 或 `$HOME/.agents/skills/fnos-cli/scripts/fnos-cli` | 需自己带 `--profile/--host/--port/--scheme` |

**外网前提**：NAS 上 `cloudflared` 隧道健康；域名 `nas.xinhaiblog.top` 可访问。

两个 profile（`nas` / `nas-lan`）使用不同 OAuth device id，禁止混用同一设备号重复授权，以免互相顶掉 refresh token。

## 首次授权（外网 Agent 必做）

在 **将要执行命令的那台机器**、同一系统用户下：

```bash
FNOS="$HOME/.cursor/skills/fnos-cli/scripts/fnos-cli"
# 若上面不存在则用：
# FNOS="$HOME/.agents/skills/fnos-cli/scripts/fnos-cli"

"$FNOS" --profile nas --host nas.xinhaiblog.top --port 443 --scheme https \
  login --authorize-only --agent-name '<agent名>'
```

1. 把返回的授权链接交给用户，用户在浏览器登录飞牛并授权。
2. 用户把一次性 code 发回对话。
3. Agent 执行（不复述、不落盘转发 code）：

```bash
"$FNOS" --profile nas --host nas.xinhaiblog.top --port 443 --scheme https \
  login --code '<用户发来的code>'
"$FNOS" --profile nas --host nas.xinhaiblog.top --port 443 --scheme https system info
```

或用包装器（已授权过 `nas` profile 后）：

```bash
FNOS_FORCE=wan $HOME/.local/bin/fnos system info
```

详细模块命令见已安装的 `fnos-cli` Skill（`entries/`、`reference/`）。本 Skill 不重复封装全部子命令；操作前对目标子命令跑 `--help`。

## 常用操作约定

- 写操作（删文件、停容器、改网络等）须确认用户意图，并带 `--yes`。
- 文件路径用具体卷路径，例如 `/vol1/1000/apps/...`。
- Docker / 应用变更后用只读命令复核状态。
- 不要把 token、PASSWORD、Tunnel token、PROXY_SECRET 打印到回复里。

## 双盘目录规范

- 全文：`/vol2/1000/LAYOUT.md`（副本 `/vol1/1000/apps/LAYOUT.md`）
- **vol1**：`apps/`、`skills/`（系统与配置）
- **vol2**：`Photos/`、`movies/`、`onedrive-sync/`、`docs/`、`backup/`、`inbox/`（数据）
- 临时文件进 `vol2/inbox/`；OneDrive 只落在 `vol2/onedrive-sync/`

## 本机已部署的相关服务（便于定位）

| 服务 | 局域网 | 公网（Cloudflare Tunnel） |
|------|--------|---------------------------|
| 飞牛面板 / API | `http://192.168.1.13:5666` | `https://nas.xinhaiblog.top` |
| LibreTV | `http://192.168.1.13:2048` | `https://tv.xinhaiblog.top` |
| LibreTV 订阅 JSON | `http://192.168.1.13:8766/jin18-libretv.json` | `https://sources.xinhaiblog.top/jin18-libretv.json` |
| MoonTV | `http://192.168.1.13:13000` | （若未配主机名则仅局域网） |
| 心海 Memos | `http://192.168.1.13:5230` | `https://app.xinhaiblog.top` |
| rclone GUI | `http://192.168.1.13:5572` | （仅局域网；登录须带 api url 参数） |

LibreTV 容器预置订阅：`DEFAULT_SUBSCRIPTIONS` → `https://sources.xinhaiblog.top/jin18-libretv.json`。

## 外网 AI 工具怎么用本 Skill

### A. Cursor / Codex 等「能跑终端」的 Agent（推荐）

1. 安装或同步本目录到该环境的 skills 路径（如 `~/.cursor/skills/fnos-nas/`）。
2. 同时具备 `fnos-cli` Skill（含 `scripts/fnos-cli`），或本机已有 `~/.local/bin/fnos`。
3. 对外网执行一次 `login`（见上文）。
4. 之后对话里提「NAS / 飞牛 / Docker / 文件」即可由本 Skill 引导操作。

云端 Agent 若在隔离机器上跑：必须能访问 `nas.xinhaiblog.top:443`，并在该隔离环境完成授权；不能复用你笔记本里未同步的本地 token 文件（除非显式迁移 CLI 凭据存储，一般不推荐）。

### B. 纯网页聊天 AI（无 shell / 无网络出站到你家）

**不能**单靠一份 Skill.md 直接操控 NAS。需要额外桥接，任选其一：

- 继续用 Cursor / 带 Computer Use 的 Agent；或
- 自建 MCP / HTTP API（在可访问 NAS 的机器上跑），把工具暴露给外部 AI。

本 Skill 覆盖场景 A；场景 B 需另做网关，不要假装网页模型能直接执行 `fnos-cli`。

## 安全

- 外网入口经 Cloudflare Tunnel，勿随意关闭 Access / 暴露未鉴权端口。
- Agent 只使用用户已授权的 profile；高风险存储/电源操作先复述再执行。
- LibreTV / MoonTV 密码与订阅内容视为敏感，默认不写入公开仓库。


## 外网 HTTP Agent API（已部署）

- 文档 / OpenAPI：`https://agent.xinhaiblog.top/docs`
- Skill 原文：`https://sources.xinhaiblog.top/skills/fnos-nas/SKILL.md`
- 鉴权：请求头 `Authorization: Bearer <NAS_AGENT_API_KEY>`（密钥在 NAS `ACCESS.txt`，勿提交到公开仓库）
- 常用接口：
  - `GET /v1/status`
  - `GET /v1/docker/containers`
  - `POST /v1/docker/containers/{name|id}/restart`
  - `GET /v1/files/list?path=/vol1/1000/apps`
  - `GET /v1/files/read?path=/vol1/1000/apps/libretv/docker-compose.yml`

纯网页 AI（ChatGPT Actions 等）把 `https://agent.xinhaiblog.top/openapi.json` 配成 Action，并带 Bearer 密钥。