飞牛 fnOS：从 Docker 创建项目到开始追番
1. 创建 Compose 项目
在飞牛的 Docker 应用中打开「Compose → 创建项目」。默认番剧目录是项目目录下的 media 文件夹，直接复制 飞牛 Compose 配置 就能安装，不需要先打开任何配置页。
要使用已有的 NAS 番剧文件夹，有两种做法：
- 直接改一行：把配置里
./media:/media左侧换成该文件夹的实际绝对路径，例如/vol1/1000/ani，右侧保持/media。先在飞牛文件管理器里建好这个文件夹。 - 或用配置页生成：把离线安装配置页下载到电脑后用浏览器打开（GitHub 文件页选「下载原始文件」；直接查看源码不会运行页面），选择「自定义」，填入实际路径，点击「复制完整配置」。页面不联网，也不需要先装容器。它保留
./data:/data，把所选媒体目录映射成/media，网页中仍填/media。
已经装好之后想换目录或端口，不必再去找文件：在局域网浏览器打开 http://NAS的局域网IP:8000/install（改过端口则用新端口），这是应用自带的同一个页面，手机也能用，不依赖境外网络。生成的配置用于新安装；已有安装必须保留原来 data 的映射，否则程序会读到另一个数据目录。
- 项目名称填
auto-anime（也可以自定义）。 - 路径选择存储空间中专门的持久化文件夹，例如「我的文件/auto-anime」。数据会写在这里，之后不要随意移动或删除。
- 粘贴上面的 Compose 内容（默认配置或配置页生成的完整配置），替换配置编辑框中的原内容。
- 确认 8000 与 6881-6890 端口段未被其他服务占用，勾选「创建项目后立即启动」，点击「确认」。
无需下载项目源码、填写 build:、安装 Go/Node.js，也无需另装 qBittorrent。模板使用 GHCR 发布镜像，安装前确认镜像已公开且对应版本存在；如果飞牛版本的按钮名称不同，选择对应的 Compose 项目创建入口即可。
端口已被占用怎么办
- 网页端口 8000 已被占用：将
"8000:8000"改为"18000:8000"，之后访问 18000。只改左侧，不改应用的PORT。 - 已运行其他 BT 下载器，6881-6890 冲突：把两行分别改为
"16881-16890:16881-16890/tcp"与"16881-16890:16881-16890/udp"，同时将NATIVE_BT_PORT改为"16881"。三处必须一致，端口段也要保持 10 个连续端口。
2. 知道文件保存在哪里
模板使用项目目录下的两个文件夹，通常由 Docker 在创建容器时建立：
| NAS 上的位置 | 容器内路径 | 用途 |
|---|---|---|
项目目录下的 data | /data | 数据库、封面、下载器会话与做种源文件 |
项目目录下的 media | /media | 整理好的番剧，供飞牛影视扫描 |
例如项目放在「我的文件/auto-anime」，媒体位于「我的文件/auto-anime/media」。网页中的媒体库填 /media；飞牛影视选择 NAS 上实际的 media 文件夹。两者名称不同，是因为通过 Compose 映射到了同一位置。
默认会保留 BT 下载器源文件供做种，再复制到媒体库，请预留两份文件的空间。首次向导可关闭「保留下载器原文件做种」；关闭后只有归档成功并写入数据库才删除源文件，归档失败时仍会保留。不要把飞牛影视媒体库指向整个 data 目录。
如果已有专门的「番剧」文件夹，只需把 ./media:/media 中左侧改为该文件夹的实际绝对路径，右侧仍为 /media。从文件管理器查看并复制真实路径，不要把「存储空间1/我的文件」这种显示名称当作系统路径，也不要照搬其他用户的 UID。
已有安装请保留原来的数据挂载。例如原来使用 ./docker-data:/data，就继续使用它；直接替换成 ./data:/data 会让程序读到另一个数据目录，看起来像丢失订阅。新增媒体目录不会搬迁旧文件。
3. 打开首次设置
容器启动后，在局域网浏览器打开 http://NAS的局域网IP:8000（改过端口则使用新端口）。这里的 IP 是 NAS 的地址，不是电脑的 127.0.0.1。
- **管理员账户：**创建 Auto-Anime 自己的用户名和密码，不要求与飞牛账户一致。
- **下载方式：**保留「内置 BT 下载器」，无需地址和密码。
- **保存目录：**模板自动使用
/media，保持不变，点击「检测保存目录」。目录检测仅检查部署时配置的根目录，通过临时文件写入、同步与删除确认权限，不会创建缺失目录或移动媒体；未映射时先修正 Compose 并重新部署。修改容器内路径收在高级选项中，订阅保存位置以后可留空沿用这里。 - **确认并开始：**默认直连、每 30 分钟同步，无需填写代理。确认目录和下载模式，点击「完成设置」。
完成页面会告诉你下一步。如果媒体库未映射，先检查 Compose 的 volumes，重建容器并在设置页改为正确容器路径，再开始下载；只改网页路径不会自动增加 Docker 映射。
检测显示「可以写入，但无法确认挂载」时仍须手动核对映射。这不是“已映射”的确认，也不保证 NAS 权限、硬盘空间或真实下载始终正常。检测接口仅在未初始化时可用，不支持从网页新增 Docker 挂载或浏览整个 NAS。
4. 添加第一部番剧
完成设置后，在「订阅管理」手动添加实际 RSS，预览资源后保存订阅。也可在「搜索」查看 Bangumi 番剧条目；候选资源需先配置在线聚合服务。保存位置先留空，使用 /media。开启自动下载后，在「最近条目」查看状态。
只有显示「已保存」的条目才表示完成归档。可在 NAS 的 media 文件夹看到 <番剧名>/Season XX/…，再将这个文件夹加入飞牛影视媒体库。
来源暂时不可达时可以换源或手动填写 RSS，不必重新安装。内置网页播放器不转码；浏览器不能解码的资源可交给媒体服务器播放。
常见安装问题
| 现象 | 下一步 |
|---|---|
| 镜像拉取超时或失败 | 查看飞牛 Docker 的错误，检查 NAS 到 ghcr.io 的连接及 Docker 镜像获取配置。网页中的出站代理不能帮助 Docker 拉取镜像；不要使用来源不明的镜像 |
| 提示找不到 Dockerfile | 使用了源码构建配置。改用本指南的发布镜像模板，移除 build: |
| 容器启动失败，提示端口已占用 | 按上面的方式调整网页或 BT 端口，并重建容器 |
| 容器运行，但网页打不开 | 核对 NAS IP、端口映射、局域网/防火墙以及容器日志 |
| 向导提示无法读取配置 | 先检查服务，再点「重新读取配置」，不要用未读到的默认值继续安装 |
| 设置保存了，但自动登录失败 | 点击「前往登录」，用刚创建的账户登录，无需重新运行向导 |
| 找不到或打不开安装配置页 | 默认配置不需要它：直接复制 飞牛 Compose 配置，或只改 ./media:/media 左侧一行。容器已启动时可在局域网访问 http://NAS的局域网IP:8000/install |
| 下载完成却归档失败 | 检查挂载、目录权限与剩余空间；如果使用外部下载器，还需核对源文件映射 |
| 已保存却在 NAS 上找不到 | 核对 /media 对应的 NAS 文件夹，检查是否写到了未映射目录；不要先删除容器或数据 |
| 重建后像全新安装 | 检查 /data 是否仍映射到原来的数据文件夹，不要覆盖或删除原数据库 |
发布镜像获取需要 NAS 能访问 GHCR；应用管理页面不依赖境外 CDN，运行时默认直连。RSS、Bangumi 元数据与版本检查分别取决于所选服务的可达性，元数据失败不影响基础订阅。
更新与备份
使用发布镜像更新时，在飞牛 Docker 中拉取新镜像并使用原项目配置重建，保留 data 与 media 的挂载。仅重启不会拉取新镜像。升级前停止实例并备份这两个文件夹。
网页 JSON 备份导出订阅、番剧配置及历史条目摘要（含资源地址、状态和文件路径），不包含账户凭据、下载器任务或媒体；恢复仅导入订阅与番剧配置，不恢复历史条目。分享前检查私人信息，不能替代文件夹备份。应用一键更新与镜像更新的差异见维护指南。
本指南依据当前配置和实现编写；飞牛界面、NAS 权限及实际下载需针对设备和发布版本验证，历史测试不代表所有安装方式都已验收。
另一种安装方式：应用包
除了上面粘贴 Compose，也可以手动安装 auto-anime-<版本>-fnos.fpk：安装向导询问 BT 端口和做种策略，提供桌面入口，默认媒体库是共享目录 auto-anime/media。自定义目录（例如 /vol1/1000/ani）时，在「应用设置 → 访问权限」授权具体文件夹，重启应用同步挂载，再在网页填写同一路径并检测，不需手工编辑 Compose。
应用包适合新用户与授权目录安装；需要保留原有数据映射或使用外部下载器时，可继续用 Compose。构建方式、权限设计与验证边界见飞牛应用包；尚未上架应用中心，安装前核对实际 Release；图形升级需按版本验收。
本页同步自仓库 docs/FNOS.md