mirror of
https://github.com/Shu-Ying/farm_service.git
synced 2026-11-02 18:50:01 +08:00
add # 初始化仓库
This commit is contained in:
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"schema": 1,
|
||||
"version": "farm-assets-v1",
|
||||
"sha256": "78d6e8e448fd5296b21d471b98ea7d58c81ef78a82b0e192a1ed041bb5fddad9",
|
||||
"size_bytes": 21264561,
|
||||
"sources": {
|
||||
"github": "https://raw.githubusercontent.com/Shu-Ying/farm_service/main/assets/assets.zip",
|
||||
"gitea": "https://gitea.diuse.work/Diuse/farm_service/raw/branch/main/assets/assets.zip",
|
||||
"farm_service": "https://farm.example/v1/assets/78d6e8e448fd5296b21d471b98ea7d58c81ef78a82b0e192a1ed041bb5fddad9/assets.zip"
|
||||
}
|
||||
}
|
||||
+163
@@ -0,0 +1,163 @@
|
||||
# 资源分发接口与三端接入约定
|
||||
|
||||
本文件位于 farm_service 项目。服务端接口及准备工具已实现，
|
||||
素材发布文件位于本仓库根目录 `assets/`。当前文件只完成本地准备，
|
||||
尚未提交或发布到 GitHub/Gitea，不能据此认定远端直链已经可用。
|
||||
活动接口尚未实施，不因为预留服务地址就返回虚构的活动数据。
|
||||
|
||||
## 已确认的客户端配置约定
|
||||
|
||||
两个配置项始终同时存在，不根据选项隐藏：
|
||||
|
||||
| 配置 | 约定 |
|
||||
| --- | --- |
|
||||
| 资源获取地址 | 选项 Github、Gitea、farm_service；默认 Github |
|
||||
| farm_service 地址 | 独立的服务基础地址，供资源、活动等功能共同使用 |
|
||||
|
||||
选择 Github 或 Gitea 时，farm_service 地址仍保留，未来活动查询仍可使用。
|
||||
选择 farm_service 获取资源时，该地址必须有效。客户端根据此配置构造
|
||||
`/v1/assets/{sha256}/assets.zip` 请求，不依赖清单中服务地址的占位值。
|
||||
三端接入状态及具体配置字段以插件实现为准，不能把此文档当作线上验证。
|
||||
|
||||
Farm当前本地已接入共享启动校验/下载器，三端插件包不再包含assets.zip。
|
||||
NoneBot字段为`FARM_RESOURCE_SOURCE`、`FARM_SERVICE_URL`；AstrBot字段为
|
||||
`resource_source`、`farm_service_url`；真寻配置名为「资源获取地址」、
|
||||
「farm_service 地址」。均默认Github，服务地址默认空，修改后重载。
|
||||
源码及离线测试已适配不代表真实公网下载或宿主验证已完成。
|
||||
|
||||
## 仓库文件与发布位置
|
||||
|
||||
```text
|
||||
assets/
|
||||
manifest.json
|
||||
assets.zip
|
||||
```
|
||||
|
||||
`assets/manifest.json` 和 `assets/assets.zip` 是实际发布文件；
|
||||
`docs/assets.manifest.example.json` 与实际清单保持一致，仅用于阅读示例。
|
||||
ZIP 从现有农场素材复制，源文件不由准备工具删除。
|
||||
后续素材发布只更新并提交 farm_service 仓库内的这组文件，
|
||||
不要把 ZIP 加回 NoneBot、真寻或 AstrBot 的插件仓库、生成目录或发布包。
|
||||
插件可以携带绑定版本的轻量清单，但不携带 `assets.zip`。
|
||||
|
||||
发布到 `main` 分支后，公开静态清单直链为：
|
||||
|
||||
- GitHub：`https://raw.githubusercontent.com/Shu-Ying/farm_service/main/assets/manifest.json`
|
||||
- Gitea：`https://gitea.diuse.work/Diuse/farm_service/raw/branch/main/assets/manifest.json`
|
||||
|
||||
对应 ZIP 位于相同目录，文件名为 `assets.zip`。选择 GitHub/Gitea 时
|
||||
可独立访问公开静态清单和 ZIP，无需 farm_service 在线。
|
||||
本轮没有提交、推送或验证这些远端文件。
|
||||
|
||||
## 服务端部署文件
|
||||
|
||||
服务不从用户输入下载ZIP，也不代理任意URL。管理员准备本地发布文件；
|
||||
`FARM_ASSET_MANIFEST`指向JSON，其同目录固定文件名为`assets.zip`。
|
||||
启动读取并检查schema、版本、URL、大小、整个ZIP的SHA256及ZIP文件头。
|
||||
校验失败拒绝启动，不对外提供损坏素材。未设置该环境变量时，其余服务
|
||||
正常启动，资源接口返回503。现有用户资料接口仍需要Bearer鉴权。
|
||||
|
||||
ZIP不解压。启用后保留最多64 MiB的单份只读内存快照，请求共享这份内容；
|
||||
不会每个请求重复读取磁盘和计算SHA。运行中修改磁盘不会改变当前返回内容，
|
||||
更新清单或ZIP需先准备一套完整目录，再修改配置并重启服务。
|
||||
当前仅托管一个活动资源版本；请求其他SHA返回404，历史版本仍需保留在
|
||||
GitHub/Gitea中，或以后扩展多版本服务。资源版本不必等于插件版本。
|
||||
|
||||
## 用Rust工具生成清单
|
||||
|
||||
不手填SHA。工具从现有ZIP计算SHA256与字节数，并复制文件、输出JSON；
|
||||
输出目录必须不存在，不覆盖旧发布目录，不上传、不访问远端。
|
||||
|
||||
[实际清单](../assets/manifest.json)及[完整JSON示例](assets.manifest.example.json)
|
||||
已使用当前农场 ZIP 生成真实 SHA 与大小。生成根目录 `assets/` 的示例如下；
|
||||
已存在时请选择新的临时输出目录，检查后再替换一整套发布文件。
|
||||
|
||||
```powershell
|
||||
cargo run --locked --bin prepare_assets -- `
|
||||
D:\Work\farm\src\farm_render\data\assets.zip `
|
||||
.\assets `
|
||||
farm-assets-v1 `
|
||||
https://raw.githubusercontent.com/Shu-Ying/farm_service/main/assets/assets.zip `
|
||||
https://gitea.diuse.work/Diuse/farm_service/raw/branch/main/assets/assets.zip `
|
||||
https://farm.example
|
||||
```
|
||||
|
||||
`https://farm.example` 是明确的占位域名（placeholder），不是已部署服务。
|
||||
目前未提供公网地址，所以实际清单及示例暂保留该值；客户端使用独立的
|
||||
「farm_service 地址」配置构造请求，不请求该占位地址。
|
||||
部署时应通过准备工具改为真实公网基础地址，支持反向代理路径前缀。
|
||||
公网访问由部署者配置HTTPS代理，
|
||||
服务仍默认监听127.0.0.1:8080。不要使用GitHub/Gitea仓库网页URL替代raw文件URL。
|
||||
|
||||
准备完成后设置环境变量（PowerShell示例）：
|
||||
|
||||
```powershell
|
||||
$env:FARM_ASSET_MANIFEST = (Resolve-Path .\assets\manifest.json).Path
|
||||
# FARM_API_TOKEN等原有必填配置沿用原部署方式，不在本文放入真实令牌。
|
||||
cargo run --locked --bin farm_service
|
||||
```
|
||||
|
||||
此时依旧需要原有用户服务的FARM_API_TOKEN；公开资源下载不使用它。
|
||||
不要将资料API令牌打包进插件或写入资源JSON。
|
||||
|
||||
## JSON协议
|
||||
|
||||
`schema`固定为1；工具实际生成有效64位小写SHA256，下面仅解释字段：
|
||||
|
||||
| 字段 | 类型 | 含义 |
|
||||
| --- | --- | --- |
|
||||
| schema | 整数 | 清单协议版本1 |
|
||||
| version | 字符串 | 资源发布标签，1～64个字母、数字、点、下划线或连字符 |
|
||||
| sha256 | 字符串 | 整个ZIP的64位小写SHA256 |
|
||||
| size_bytes | 整数 | ZIP字节数，1～67,108,864 |
|
||||
| sources.github | 字符串 | GitHub绝对HTTPS下载URL |
|
||||
| sources.gitea | 字符串 | Gitea绝对HTTPS下载URL |
|
||||
| sources.farm_service | 字符串 | 服务绝对HTTPS下载URL，包含相同SHA256 |
|
||||
|
||||
JSON不接受未知字段；URL不允许凭据、查询参数或fragment。
|
||||
清单大小限制16 KiB。服务端校验本地ZIP，不会主动探测两个镜像是否一致；
|
||||
发布者须确保三源文件字节相同。主分支raw文件可能变更，长期建议采用
|
||||
固定提交、标签或Release附件直链。SHA固定而raw发生变化时，客户端必须
|
||||
拒绝新字节，不能通过重新获取任意清单来跳过版本兼容性检查。
|
||||
|
||||
## HTTP接口
|
||||
|
||||
### GET /v1/assets/manifest.json
|
||||
|
||||
公开，无需资料API令牌；200返回上述JSON，Cache-Control为no-cache。
|
||||
未启用资源服务时503，错误码`assets_unavailable`。
|
||||
|
||||
### GET /v1/assets/{sha256}/assets.zip
|
||||
|
||||
公开，只有SHA与当前校验资源一致时返回200，Content-Type为application/zip。
|
||||
下载内容与清单的SHA及大小一致；ETag为带双引号的完整SHA。
|
||||
支持If-None-Match条件请求，命中返回304；返回不可变长期缓存标记。
|
||||
未知或旧SHA返回404及`asset_not_found`。不支持任意路径访问，也不执行解压。
|
||||
不是活动接口，不读取玩家库。未启用资源服务时返回503。
|
||||
|
||||
## 三端下载器接入约定
|
||||
|
||||
1. 启动时计算本地ZIP的SHA256；符合插件绑定的资源版本和摘要则直接复用。
|
||||
2. 缺失或不匹配才按「资源获取地址」选择源下载；网络不可用不应损坏旧文件。
|
||||
3. 将内容下载到临时文件，限制字节数和超时，校验大小、SHA及必要ZIP条目，
|
||||
通过后原子替换，避免并发启动重复下载。
|
||||
4. 只有摘要和布局元数据匹配的ZIP才能参与绘图，不能任意跟随服务的最新版本。
|
||||
5. 清单可以从farm_service接口读取，也可将工具生成的同一JSON发布到镜像，
|
||||
并随插件保留经过版本绑定的清单，避免选择Github后又强依赖服务在线。
|
||||
6. 三端共用同一实现；无可用素材时保留文字功能并提示管理员，不能使用损坏包。
|
||||
7. 当前按所选源下载，不自动跨源回退；失败保留文字模式，调整配置后重载重试。
|
||||
8. 本地缓存路径为插件数据目录`assets/<sha256>/assets.zip`，可手动预置离线包。
|
||||
同进程并发启动合并下载，跨进程使用独立临时文件与原子替换保证写入完整。
|
||||
不解压到磁盘，缓存中存在旧版本时不自动删除，便于回滚。
|
||||
|
||||
## 离线验证
|
||||
|
||||
```text
|
||||
cargo fmt --check
|
||||
cargo test --locked --offline --all-targets
|
||||
cargo clippy --locked --offline --all-targets -- -D warnings
|
||||
```
|
||||
|
||||
测试覆盖公开清单、ZIP下载、条件缓存、磁盘变动后快照一致性、损坏/缺失
|
||||
文件及非法URL拒绝、资源未启用，另保留原用户接口鉴权和持久化测试。
|
||||
离线验证不代表真实公网部署、镜像发布或三端集成完成。
|
||||
@@ -0,0 +1,36 @@
|
||||
# 初始化验证记录
|
||||
|
||||
日期：2026-10-21。验证环境：Windows，rustc/cargo 1.98.0。
|
||||
|
||||
## 已完成
|
||||
|
||||
- 从用户指定的空仓库克隆至 `D:\Work\farm_service`。
|
||||
- 初始化 Rust 2024 二进制应用和中文 README；协议初始为 MIT，后于
|
||||
2026-10-21 按用户选择切换为 AGPL v3（AGPL-3.0-only）。
|
||||
- 用户资料使用单条 SQLite UPSERT 原子写入，按平台和用户 ID 去重。
|
||||
- 首次正常编译完成，生成 `Cargo.lock`。
|
||||
- `cargo test --all-targets`：6 项集成测试通过，无失败。
|
||||
- `cargo fmt --check`：通过。
|
||||
- `cargo clippy --locked --all-targets -- -D warnings`：通过，无警告。
|
||||
- 真实本机 HTTP：健康检查、资料写入、资料读取、无令牌 401 均通过。
|
||||
- 指定 info 日志级别，确认启动及资料写入事件写入每日 JSON 文件；
|
||||
日志只记录事件和平台，不包含测试用户 ID、昵称或令牌。
|
||||
- Git 忽略规则实际检查：target、数据库、日志、.env、.env.local 被忽略；
|
||||
Cargo.lock、.env.example 可纳入版本控制。
|
||||
|
||||
## 验证边界
|
||||
|
||||
- 测试使用临时数据库与合成资料；没有采集真实 QQ 用户信息。
|
||||
- 测试 HTTP 进程已停止；没有部署常驻服务。
|
||||
- 未接入农场插件自动上报，未验证真实 QQ 群、官方 QQ 或公网代理。
|
||||
- 本轮未实现活动管理、中心账本、多租户鉴权、用户删除及数据自动清理。
|
||||
- 未执行 Linux 运行验证、依赖漏洞专项扫描或生产负载测试。
|
||||
- 未提交、推送或创建 PR。新文件保留在本地仓库，供后续检查。
|
||||
|
||||
## 后续接入顺序
|
||||
|
||||
1. 在农场接入层取得可信的 QQ 号码与昵称，确认信息用途及保留政策。
|
||||
2. 将平台命名空间明确为普通 qq，不能将官方 QQ OpenID 填成 QQ 号码。
|
||||
3. 用仅保存在服务端和机器人配置中的令牌调用资料接口。
|
||||
4. 为上报配置短超时；资料服务故障不能回滚已完成的基础农场操作。
|
||||
5. 生产部署前落实 HTTPS、限流、访问日志脱敏、资料删除与备份政策。
|
||||
Reference in New Issue
Block a user