APP 使用文档

Harvest 是一个用于 PT 站点数据查看、站点维护、下载器管理、资源搜索和自动化任务处理的客户端。应用支持移动端、桌面端和 Web 端，部分能力会根据平台有所差异。

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:8000
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 端不显示。
• 头像菜单：用户相关操作、主题设置、截图分享、更新入口和日志中心。

3. 仪表盘

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

常见信息包括：

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

常用操作：

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

4. 站点管理

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

4.1 查看与筛选站点

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

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

4.2 添加站点

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

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

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. 任务中心

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

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

6.1 普通任务

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

6.2 种子迁移任务

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

主要配置：

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

7. 搜索

搜索页提供两种模式：

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

7.1 搜索信息

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

7.2 搜索资源

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

搜索设置支持：

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

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

7.3 搜索历史

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

8. 资讯

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

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

9. 通知与公告

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

常用操作：

• 查看通知详情。
• 标记通知已读。
• 在设置中心配置通知渠道和通知开关。

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

10. 设置中心

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

主要设置项：

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

11. 用户中心

11.1 用户中心

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

12. 更新与升级

12.1 程序更新

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

12.2 APP 升级

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

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

13. 主题、窗口和日志

13.1 主题设置

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

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

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

13.2 截图分享

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

13.3 日志中心

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

14. 常见问题

14.1 登录失败

检查：

• 服务器地址是否包含 http:// 或 https://。
• 后端服务是否可访问。
• 账号和密码是否正确。
• Web 端是否部署在正确的后端地址下。

14.2 站点刷新或签到失败

检查：

• Cookie 是否过期。
• 站点配置是否正确。
• 站点是否启用。
• 后端是否能访问该站点。

14.3 搜索资源没有结果

检查：

• 是否已有可搜索的站点。
• 搜索设置中是否关闭了站点参数。
• 最大站点数是否过小。
• 关键词是否过于严格。
• 站点 Cookie 是否可用。

14.4 下载器连接失败

检查：

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

14.5 通知收不到

检查：

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

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

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