APP 使用文档

Harvest 是面向 Go Harvest / PT 收割机后端的 Flutter 客户端。它把 PT 站点维护、仪表盘、下载器管理、种子操作、影视资讯、聚合搜索、计划任务、通知、日志排查和客户端更新集中在一个 App 内。

支持平台：

• Web。
• Android / iOS。
• macOS / Windows / Linux。

不同后端版本、账号权限和平台能力会影响部分入口是否显示。

文档导读

第一次使用建议按这个顺序阅读：

1. 登录与账号：确认后端地址并完成首次初始化或登录。
2. 主界面导航：了解桌面端、移动端和 Web 端入口差异。
3. 设置中心：配置通知、CookieCloud、搜索和第三方工具。
4. 站点管理 与 下载器管理：添加站点和下载器后开始日常使用。
5. 常见问题：遇到登录、站点、搜索、下载器或日志问题时排查。

功能速查：

最近变化

• 桌面体验：登录历史页预留 macOS/Linux 窗口按钮空间；菜单栏授权信息跟随隐私开关；macOS/Windows 关闭窗口时增加退出确认。
• 站点与仪表盘：站点卡片上传/下载总量自适应显示；长截图锁定主体内容区域。
• 设置与通知：新增微信/QQ 机器人通知入口，完善微信机器人配置工具；通知测试参数修复；药丸和蜂巢抓取 token 后可直接写入站点信息；设置页保留表单状态。
• 日志与输入：日志浮窗断线后自动重连，连续三次失败后停止；修复移动端输入框长按菜单异常。
• 升级安装：优化 GitHub 加速信息显示；修复 macOS APP 更新安装包打开方式；macOS .pkg 安装前会退出 /Applications/harvest.app 中正在运行的程序。

1. 登录与账号

1.1 登录

打开 APP 后进入登录页，依次填写：

• 服务器地址：Harvest 后端服务地址，例如 https://example.com。Web 端通常会从当前页面地址自动识别，输入框不可编辑。
• 账号：后端账号用户名。
• 密码：后端账号密码。

点击“登录”后，APP 会连接服务器并恢复用户信息。登录成功后默认进入“仪表盘”。

1.2 首次初始化入口

当 Go Harvest 后端还没有完成初始化时，APP 会在登录前自动检测初始化状态。触发方式有两种：

• 输入服务器地址后点击“登录”，APP 访问初始化状态接口，发现后端需要初始化时会打开“Go Harvest 初始化”窗口。
• 如果直接登录时后端返回“尚未初始化”或提示 /setup，APP 也会自动打开初始化窗口。

初始化窗口用于一次性写入后端运行所需的数据库连接、管理员账户和 JWT Secret。完成后，APP 会自动把刚创建的管理员用户名和密码填回登录页，并提示“初始化完成，请登录”。

1.3 初始化前准备

初始化前请先确认：

• 后端服务已经启动，并且 APP 中填写的服务器地址可以访问。
• 如果使用 PostgreSQL，数据库服务已经启动，网络可达，并且准备好了可连接的数据库账号。
• 如果使用 SQLite，后端运行目录需要有权限创建或写入 db/data.sqlite3。
• 管理员密码至少 6 位。

服务器地址必须以 http:// 或 https:// 开头，例如：

http://192.168.1.10:5173
https://harvest.example.com

1.4 数据库初始化配置

初始化窗口的“数据库”区域支持两种类型。

PostgreSQL：

• 类型：选择 PostgreSQL。
• 地址：数据库主机地址，默认 127.0.0.1。
• 端口：数据库端口，默认 5432。
• 数据库名：默认 goharvest。
• 数据库用户：默认 goharvest。
• 数据库密码：填写对应数据库用户的密码。
• 开启数据库调试日志：用于排查 SQL 或连接问题，生产环境通常可以关闭。

SQLite：

• 类型：选择 SQLite。
• 数据库文件：固定为 db/data.sqlite3，界面中不可编辑。
• SQLite 不需要填写地址、端口、数据库用户和数据库密码。

选择数据库类型时，APP 会自动切换需要填写的字段。PostgreSQL 模式下，地址、端口、数据库名和数据库用户不能为空。

1.5 管理员账户配置

初始化窗口的“管理员”区域用于创建第一个登录账号：

• 用户名：默认 admin，不能为空。
• 邮箱：可选，用于记录管理员邮箱。
• 密码：不能为空，至少 6 位。

初始化成功后，这个账号就是首次登录使用的账号。APP 会自动把用户名和密码填入登录表单，但仍需要点击“登录”进入系统。

1.6 JWT Secret

JWT Secret 用于后端签发和校验登录令牌。初始化窗口会自动生成一个随机值，也可以点击“重新生成”换一个新值。

建议：

• 首次初始化时使用自动生成的随机值。
• 不要使用过短或容易猜到的字符串。
• 初始化后不要随意更改后端保存的 JWT Secret，否则已有登录令牌可能失效。

1.7 提交初始化

确认数据库和管理员信息无误后，点击“开始初始化”。

提交后可能出现以下结果：

• 成功：窗口关闭，登录页自动填入管理员账号和密码，点击“登录”进入系统。
• 失败：窗口内会显示错误信息，可根据提示修正配置后再次提交。

常见失败原因：

• PostgreSQL 地址或端口不可达。
• 数据库名、数据库用户或密码不正确。
• 数据库用户没有建表或写入权限。
• SQLite 文件目录没有写入权限。
• 管理员用户名为空或密码少于 6 位。
• JWT Secret 为空。

1.8 登录历史与切换账号

当本机保存了多个登录记录时，登录页会显示“登录历史”入口。进入后可以选择历史账号快速登录。

登录后也可以从左侧抽屉或头像菜单进入“切换账号”。切换账号会退出当前会话并进入登录历史页。

1.9 退出登录

从左侧抽屉或头像菜单点击“退出登录”。退出后会清除当前登录态，并返回登录页。

2. 主界面导航

登录后主界面包含顶部栏、页面内容区和底部/侧边导航。

主要页面：

• 资讯：查看 TMDB、豆瓣等媒体信息入口。该页面可在设置中关闭，关闭后默认进入仪表盘。
• 站点：维护 PT 站点配置和站点状态。
• 仪表：查看站点数据、服务器状态、后台服务状态和趋势图表。
• 下载：管理 qBittorrent / Transmission 下载器。
• 任务：管理定时任务和种子迁移任务。
• 搜索：从底部导航或搜索按钮进入，支持影视信息搜索和站点资源搜索。

左上角菜单按钮或从屏幕左侧边缘向右滑动可打开抽屉。抽屉包含主要页面、设置中心、用户中心、程序更新、APP 升级、日志中心等入口。

顶部栏还会显示：

• 通知铃铛：进入通知历史，未读通知会滚动展示。
• 程序更新角标：有后端程序更新时显示。
• APP 升级红点：有客户端新版本时显示，Web 端不显示。
• 头像菜单：用户相关操作、主题设置、截图分享、更新入口和日志中心。

2.1 桌面端菜单

桌面宽度下，登录后左侧会显示常驻 NavigationSidebar 菜单。菜单包含：

• 数据仪表、全局搜索。
• 资讯中心、站点数据、站点动态。
• 下载管理、任务列表。
• 设置中心、程序更新、应用升级。
• 日志中心、日志浮窗。
• 用户中心、授权管理。
• 服务重启、切换账号、退出登录。

顶部栏最左侧菜单按钮在桌面端用于显示或隐藏常驻菜单；在移动端用于打开抽屉。菜单隐藏时，macOS/Linux 桌面端会在 header 左侧保留窗口按钮空间，Web 端不会保留该空间。

桌面端菜单栏中的授权信息会跟随隐私开关隐藏或显示。macOS 和 Windows 下点击关闭按钮或使用窗口关闭快捷键时，会弹出退出确认，避免误关正在使用的客户端。

2.2 移动端与 Web

移动端通过底部导航和左侧抽屉使用主要入口。Web 端不显示本地窗口控制按钮，也不会预留桌面窗口按钮位置。移动端输入框支持系统长按菜单，用于粘贴、选择和编辑文本。

3. 仪表盘

仪表盘用于集中查看当前账号下的关键运行数据。

常见信息包括：

• 服务器状态：系统运行时间、CPU、内存、网络上传/下载等。
• 后台服务状态：后端服务监控与运行状态。
• 数据总览：总上传、总下载、做种、下载、发种等统计。
• 趋势图表：上传 / 下载趋势、今日上传 / 下载分布、站点数据分布、做种分布等。

常用操作：

• 刷新站点数据：触发站点数据刷新任务。
• 签到任务：触发站点签到任务。
• 查看图表提示：在图表上悬停或点击可查看详细数据。
• 隐私截图：头像菜单中的“截图分享”会临时开启隐私模式并保存截图，避免敏感信息泄露。

长截图会锁定在主体内容区域执行，避免把外层窗口、标题栏或无关边栏截入图片。

4. 站点管理

“站点”页面用于添加、编辑、筛选、浏览和维护 PT 站点。

4.1 查看与筛选站点

页面顶部提供搜索框和筛选入口，可按站点名称、状态、排序字段等条件筛选站点。站点卡片支持不同显示样式。

如果当前没有站点，可以点击“添加站点”或“上传配置”开始配置。

站点卡片通常显示上传量、下载量、分享率、魔力值、做种数、发布数、HR、邀请、消息、公告、等级、注册时间和最后同步时间。上传总量和下载总量会根据可用空间自适应显示，减少大数字溢出。

自定义图标会优先适配 PNG、GIF、JPG/JPEG、WebP、ICO 等常见格式，失败时回退默认图标。

4.2 添加站点

点击“添加站点”后，从未添加的内置站点配置中选择目标站点，并填写账号、Cookie、标签、是否启用等信息。

保存后站点会进入站点列表，后续可刷新状态、签到或查看详情。

也可以通过 CookieCloud、PTPP、PT-depiler 或数据备份导入站点数据。站点配置常见字段包括用户名、密码、Cookie、User-Agent、代理、镜像地址、站点标签，以及是否启用、是否签到、是否参与辅种等能力开关。

4.3 上传站点配置

点击“上传配置”选择 TOML 配置文件。上传成功后，新的站点配置会保存到服务器，可用于添加站点。

4.4 站点操作

在站点卡片上打开操作菜单，可执行：

• 详情：查看站点统计、状态图表、用户信息和历史数据。
• 编辑：修改站点账号、Cookie、标签、启用状态等配置。
• 刷新：立即刷新该站点状态。
• 签到：对未签到站点执行签到。
• 辅种：对该站点执行辅种任务。
• 浏览：打开首页、搜索页等站点地址。桌面/移动端可选择内置浏览器或外部浏览器，Web 端通常使用外部浏览器。
• 删除：从账号中删除该站点。

4.5 站点时间轴

从抽屉进入“站点时间轴”。该页面按站点创建时间、开放时间、邀请数量等维度展示站点列表，支持：

• 筛选站点范围。
• 按邀请状态筛选。
• 排序字段和排序方向切换。
• 控制标题和显示字段，例如下载量、邀请数、用户名。
• 打开站点地址或查看站点详情。

4.6 站点配置生成器

站点配置生成器可用于编辑或生成 TOML 配置模板，支持配置名称、模板字段、用户等级等内容，并可分享、下载或保存到服务器。

5. 下载器管理

“下载”页面用于管理 qBittorrent 和 Transmission 下载器。

5.1 下载器列表

页面展示所有下载器卡片，并显示实时状态：

• 实时速度接收状态。
• 启用下载器数量。
• 辅种下载器数量。
• 下载器总数。

支持下拉刷新。顶部状态栏可暂停或恢复实时状态刷新，也可以进入刷新设置调整刷新间隔、持续时间和自动启动策略。

5.2 添加下载器

点击“添加下载器”，填写：

• 名称。
• 客户端类型：qBittorrent 或 Transmission。
• 协议、主机、端口。
• 用户名、密码。
• External Host。
• 种子路径。

保存后下载器会出现在列表中。

5.3 下载器操作

打开下载器卡片菜单，可执行：

• 种子列表：进入该下载器的种子管理页。
• 添加种子：填写种子链接、保存路径、标签、分类、暂停下载、停止条件、分享限制等信息并推送。
• 编辑 / 删除下载器。
• 启用 / 停用下载器。
• 开启 / 关闭辅种。
• 执行辅种。
• 设置：打开 qBittorrent 或 Transmission 参数设置。
• 限速设置：快速进入带宽限制相关设置。
• 分类管理、标签管理：qBittorrent 专用。

5.4 下载器参数设置

qBittorrent 和 Transmission 都提供参数设置入口。常见设置包括：

• 下载设置：保存目录、临时目录、自动开始、完成后处理等。
• 带宽设置：下载 / 上传限速、备用带宽。
• 网络设置：端口、连接数、加密、PEX、LPD 等。
• 队列设置：下载队列、上传队列、无流量处理策略。

保存后配置会提交到对应下载器。

6. 种子列表与种子操作

从下载器进入种子列表后，可管理下载器内的种子。

列表能力：

• 状态筛选。
• 分类、标签、站点筛选。
• 搜索和排序。
• 桌面端详情面板。
• 移动端详情 Sheet。
• 实时速度和状态刷新。

单个或批量操作包括：

• 开始、暂停、强制启动。
• 删除种子，可选择是否删除文件。
• 重新校验。
• 重新汇报。
• 修改保存位置。
• 设置分类和标签。
• 自动管理。
• 上传速度限制。
• 分享率限制。
• 超级做种。
• 修改 Tracker。
• 导出 .torrent。
• 队列移动到顶部、向上、向下或底部。
• 复制名称、哈希、磁力链接、Tracker、保存路径等信息。

7. 任务中心

“任务”页面用于查看和管理后端自动化任务。

页面顶部显示任务启用和禁用数量，支持下拉刷新。

7.1 普通任务

点击“添加任务”并选择“普通任务”，可创建常规定时任务。编辑时配置任务名称、执行内容、调度表达式、启用状态等信息。

7.2 种子迁移任务

点击“添加任务”并选择“种子迁移任务”，可创建下载器之间的迁移流程。

主要配置：

• 任务名称。
• 源下载器：迁移任务读取种子和保存路径的下载器。
• 目标下载器：迁移后的种子推送到该下载器。
• 开启任务：关闭后不会被调度执行。
• 跳过校验：目标为 qBittorrent 时生效。
• 删除源种子：任务完成后是否删除源下载器中的种子。

任务执行记录会显示任务名称、状态、开始时间、结束时间、任务 ID 和 Markdown/JSON 详情。运行中或等待中的任务可取消，已完成的任务可删除记录，也可以清理全部执行记录。

8. 搜索

搜索页提供两种模式：

• 搜索信息：从 TMDB / 豆瓣搜索电影、剧集等媒体信息。
• 搜索资源：从已配置站点搜索种子资源。

8.1 搜索信息

输入影视名称后按回车或点击搜索。结果会展示媒体基础信息，可用于确认名称、年份、评分、简介等。

8.2 搜索资源

切换到“搜索资源”，输入资源关键词后搜索。资源搜索依赖已配置且可搜索的站点。

搜索设置支持：

• 最大站点数：单次搜索从多少个站点获取结果，0 表示全部。
• 指定站点：选择参与搜索的站点。
• 是否只使用存活且可搜索的站点。
• 过滤条件，例如“不看 HR”。

搜索结果中可选择下载器并推送种子。

资源结果支持按标题、副标题、大小、做种数、发布时间排序，也支持按站点、促销、分类、分辨率、标签、季、集数、HR 和文件大小范围筛选。发布时间会解析完整时间并显示为相对间隔，悬停时显示具体时间。

8.3 搜索历史

搜索页会保留历史关键词，便于快速重复搜索。可清除历史记录。

9. 资讯

“资讯”页面提供 TMDB 和豆瓣相关内容入口。可以在顶部标签中切换数据源。

如果不需要资讯页，可在设置中关闭媒体信息功能。关闭后底部导航和抽屉会隐藏资讯入口。

10. 通知与公告

顶部通知按钮进入通知历史。未读通知会在顶部栏展示，多个通知会轮播。

常用操作：

• 查看通知详情。
• 标记通知已读。
• 全部标记已读。
• 删除单条通知。
• 删除全部通知。
• 打开通知内链接。
• 在设置中心配置通知渠道和通知开关。

桌面端和移动端会尽量使用系统通知能力；不同平台的权限和表现可能不同。

Markdown 内容支持多行选择。顶部未读通知会在主界面 header 中显示，桌面端可显示摘要。

通知通道、通知测试、企业微信、微信机器人和 QQ 机器人的完整配置见 通知配置。

11. 设置中心

从抽屉进入“设置中心”。

主要设置项：

• 喵呜通知：配置通知 WebHook、Token 等。
• 微信机器人：配置 iLink Bot token、接收人和扫码登录。
• QQ 机器人：配置 AppID、Secret、用户 OpenID 和消息接收。
• 通知开关：控制公告详情、站点消息、下载器消息等通知类型。
• CookieCloud：同步浏览器 Cookie 到站点配置。
• 影视 Token：配置 TMDB、豆瓣等影视信息源相关 token。
• 聚合搜索配置：设置搜索站点数量和并发数量。
• 程序更新：查看后端组件更新状态，并打开完整更新页面。
• 自动刷新频率：设置 APP 前台自动刷新数据的间隔。
• 数据导入：从 PTPP、PTD、CookieCloud、收割机等来源导入数据。
• 数据备份：导出或导入备份文件。
• 批量替换：批量替换指定字段内容。
• 网络测速：提交后端网络测速任务，完成后留意通知。
• 通知测试：发送测试通知，验证通知配置是否可用。

设置中心页面会保留当前配置表单状态，切换页面后再返回时不易丢失未提交的输入。药丸和蜂巢工具抓取到 token 后，可以直接写入对应站点信息，减少手动复制和粘贴。

通知渠道和测试方式统一维护在 通知配置。

数据导入导出入口用于迁移、备份和恢复数据。

12. 用户中心

12.1 用户中心

用户中心用于查看和管理当前服务器用户。支持搜索用户名、邮箱或 ID。具体可用操作取决于当前账号权限。

13. 更新与升级

13.1 程序更新

“程序更新”用于查看后端程序或服务组件更新。顶部栏出现更新角标时，可点击进入更新页。

程序更新页用于检查和更新后端程序、Web UI 和站点配置。支持查看远端更新日志和执行更新操作。

13.2 APP 升级

非 Web 平台支持 APP 升级检查。顶部栏出现红点或抽屉中点击“APP升级”可进入升级页。

Web 端不会显示 APP 升级入口。

APP 升级页支持查看最新版本、历史版本、更新日志、下载页、GitHub 加速地址测速、下载安装包、取消下载、不再提醒某版本和 TestFlight 跳转。GitHub 加速页会显示当前加速信息。

桌面安装包选择建议：

• macOS 日常升级优先使用 .pkg，适合覆盖安装到 /Applications。
• macOS 手动拖拽安装可使用 .dmg。
• Windows 安装程序适合普通用户，.zip 适合免安装使用。
• Linux .tar.gz 解压后运行发行版 bundle。

macOS .pkg 安装到 /Applications/harvest.app。安装前如果检测到 /Applications/harvest.app/Contents/MacOS/harvest 正在运行，会先请求退出，等待最多 15 秒后仍未退出则结束进程，然后继续覆盖安装。

14. 主题与窗口

14.1 主题设置

从头像菜单点击“主题设置”，可调整：

• 明暗模式。
• 主色和基础色。
• 显示密度。
• 界面缩放。
• 桌面端窗口预设尺寸。

桌面端手动调整窗口大小后，APP 会记住窗口尺寸，下次打开时自动复原。

14.2 截图分享

非 Web 平台可在头像菜单点击“截图分享”。APP 会临时开启隐私模式、暂停实时速度刷新并保存当前页面截图。截图完成后会恢复原状态。

15. 日志中心与日志浮窗

登录页、抽屉和头像菜单均可进入日志中心。遇到登录失败、网络异常、任务失败等问题时，可先查看日志定位原因。

日志中心支持 APP 日志和服务端日志：

• 查看 APP 日志。
• 连接服务端日志。
• 顶部下拉加载更早日志。
• 跟随最新日志。
• 日志级别过滤：ALL、V、D、I、W、E。
• 放大/缩小字体。
• 快速到顶和快速到底。
• 复制当前日志。
• 分享日志。
• 清空当前视图。
• 重载当前来源。
• 多行选择日志内容。

日志浮窗可在任意页面打开，适合边操作边排查。浮窗支持 APP/服务端日志切换、LIVE/PAUSE 跟随控制、服务端 SSE 日志流、日志级别过滤、复制、分享、清空、拖动位置和调整大小。服务端日志断开后会自动重连，连续重试三次失败后停止连接。

16. 常见问题

16.1 登录失败

检查：

• 服务器地址是否包含 http:// 或 https://。
• 后端服务是否可访问。
• 后端是否已完成初始化。
• 账号和密码是否正确。
• Web 端是否被 CORS 或 HTTPS 混合内容限制。
• Web 端是否部署在正确的后端地址下。

16.2 站点刷新或签到失败

检查：

• Cookie 是否过期。
• User-Agent 是否与 Cookie 来源一致。
• 站点配置是否正确。
• 站点是否启用。
• 站点是否需要代理。
• 后端是否能访问该站点。
• 服务端日志中的站点错误。

16.3 搜索资源没有结果

检查：

• 是否已有可搜索的站点。
• 搜索设置中是否关闭了站点参数。
• 最大站点数是否过小。
• 关键词是否过于严格。
• 站点 Cookie 是否可用。
• 后端资源搜索接口是否正常。

16.4 下载器连接失败

检查：

• 下载器主机、端口、协议是否正确。
• 用户名和密码是否正确。
• 下载器 Web UI 是否启用。
• 后端服务器是否能访问下载器地址。
• qBittorrent / Transmission 类型是否选择正确。
• 是否需要配置 External Host。

16.5 通知收不到

检查：

• 设置中心中的通知 WebHook 和 Token 是否正确。
• 通知开关是否启用。
• 系统通知权限是否允许。
• 后端任务是否实际产生通知。

微信机器人通知如果返回 ret=-2，通常需要先给微信机器人发送一条消息以激活会话。

更多通知通道排查见 通知配置。

16.6 日志浮窗一直显示连接中

检查：

• 服务端日志接口是否可访问。
• Token 是否有效。
• 浏览器网络面板中 SSE 是否持续连接。
• 服务端是否返回标准 SSE 或单行 data: {...} 日志事件。

16.7 Web 端布局异常

Web 端没有本地窗口按钮，也不会预留窗口控制空间。如果出现 header 偏移，刷新页面或检查是否使用了桌面客户端构建。

16.8 桌面端窗口尺寸没有恢复

窗口尺寸只在桌面端保存。最大化、最小化、全屏时不会覆盖保存尺寸。请先恢复到普通窗口状态并调整大小，再关闭和重新打开 APP。