提交

readme.md

@@ -3,11 +3,11 @@
 一个运行在 Cloudflare Workers 上的单用户联邦宇宙发布软件,使用:
 
 - Workers: HTTP API、ActivityPub 路由、Mastodon API 兼容层
-- D1: 用户、OAuth 应用、嘟文、媒体索引、关注、收藏、转发、通知、提及、话题标签、远端 actor 缓存
+- D1: 用户、OAuth 应用/Token、嘟文、媒体索引、关注、收藏、转发、通知、提及、话题标签、收藏夹、置顶、远端 actor 与远端嘟文缓存
 - R2: 媒体文件
-- KV: OAuth access token 会话
+- KV: OAuth access token 会话(D1 同步保留,便于管理)
 
-当前目标:让常见 Mastodon App 完成实例发现、创建 OAuth App、登录、上传媒体、发布嘟文、读取公开/家庭时间线、收藏/转发/回复、查看通知、搜索、关注/取关远端账号,同时支持单用户实例与 Fediverse 双向联邦。
+当前目标:让常见 Mastodon App 完成实例发现、创建 OAuth App、登录、上传媒体、发布嘟文、读取公开/家庭/话题时间线、收藏/转发/回复/收藏夹/置顶、查看通知、搜索、关注/取关远端账号,同时支持单用户实例与 Fediverse 双向联邦。
 
 ## 本地运行
 
@@ -43,6 +43,15 @@ wrangler secret put ADMIN_PASSWORD
 
 一旦开始对外联邦后,不要再改域名,否则远端会把你视为另一个实例身份。
 
+### 媒体 CDN 加速(可选但推荐)
+
+默认情况下,客户端拉取上传媒体走 `${PUBLIC_BASE_URL}/media/<key>`,会经过 Worker 反代 R2,消耗 Worker 请求数和 CPU。生产建议:
+
+1. 在 Cloudflare R2 控制台给 `toot-media` 绑定一个 custom domain(如 `media.social.example.com`),开启公开访问 + CDN。
+2. 把该域名填进 `wrangler.jsonc` 的 `MEDIA_BASE_URL`,例如 `"MEDIA_BASE_URL": "https://media.social.example.com"`。
+
+设置后,Mastodon 客户端拿到的 `media_attachments.url` 会直接指向 CDN 域名,不再经过 Worker。Worker 自己的 `/media/<key>` 路径仍然保留,可以作为后备访问入口。
+
 ## Cloudflare 资源
 
 ```bash
@@ -86,11 +95,14 @@ npm run deploy
 - `GET /api/v1/statuses/:id/context`
 - `POST /api/v1/statuses/:id/favourite`、`/unfavourite`(联邦 Like / Undo Like)
 - `POST /api/v1/statuses/:id/reblog`、`/unreblog`(联邦 Announce / Undo Announce)
-- `POST /api/v1/statuses/:id/bookmark`、`/unbookmark`、`/pin`、`/unpin`(本地 stub)
+- `POST /api/v1/statuses/:id/bookmark`、`/unbookmark`、`/pin`、`/unpin`(本地落库)
+- `GET /api/v1/bookmarks`、`GET /api/v1/favourites`(列出本地 bookmark / favourite)
 
 时间线 / 通知 / 媒体 / 搜索 / 其它:
 
-- `GET /api/v1/timelines/public`、`GET /api/v1/timelines/home`(分页支持 `max_id` / `since_id` / `min_id`,响应携带 `Link` 头)
+- `GET /api/v1/timelines/public`(分页支持 `max_id` / `since_id` / `min_id`,响应携带 `Link` 头)
+- `GET /api/v1/timelines/home`(合并本地嘟文 + 关注的远端账号缓存嘟文,按时间排序)
+- `GET /api/v1/timelines/tag/:tag`、`GET /api/v1/tags/:name`(话题时间线 + 话题元数据)
 - `GET /api/v1/notifications`、`POST /api/v1/notifications/clear`、`POST /api/v1/notifications/:id/dismiss`
 - `POST /api/v1/media`、`POST /api/v2/media`、`PUT /api/v1/media/:id`
 - `GET /api/v2/search`、`GET /api/v1/search`(本地账号 / 嘟文 / 话题标签 + 跨站 WebFinger 解析 `acct:` 查询)
@@ -108,7 +120,7 @@ npm run deploy
 - `POST /users/:username/inbox`、`POST /inbox`(共享 inbox)
 - `GET /objects/:id`(嘟文已删除时返回 `Tombstone`,HTTP 410)
 
-入站 inbox 处理类型:`Follow` / `Undo(Follow)` / `Accept(Follow)` / `Reject(Follow)` / `Like` / `Undo(Like)` / `Announce` / `Undo(Announce)` / `Delete(Note)` / `Delete(Person)` / `Update(Person)` / `Create(Note)`(只用于触发提及通知)。`Create` 用于触发提及通知和回复通知。
+入站 inbox 处理类型:`Follow` / `Undo(Follow)` / `Accept(Follow)` / `Reject(Follow)` / `Like` / `Undo(Like)` / `Announce` / `Undo(Announce)` / `Delete(Note)`(同时清远端嘟文缓存)/ `Delete(Person)`(同时清缓存与关注关系)/ `Update(Person)` / `Update(Note)` / `Create(Note)`(被关注的远端账号公开嘟文会写入 `cached_statuses` 给 home timeline 使用,同时若 mention/回复本地用户会触发通知)。
 
 ## 安全
 
@@ -128,14 +140,15 @@ npm run deploy
 
 - `migrations/0001_initial.sql` — 基础表(users / oauth_apps / oauth_codes / statuses / media / follows / remote_activities)
 - `migrations/0002_features.sql` — 通知 / 收藏 / 转发 / 提及 / 话题标签 / actor 缓存 / 出站关注 / 删除墓碑 / 嘟文扩展字段(summary / sensitive / language)
+- `migrations/0003_bookmarks_cache.sql` — 收藏夹(bookmarks)/ 置顶(pinned_statuses)/ 远端嘟文缓存(cached_statuses)/ OAuth Token 持久表
 
 ## 重要限制
 
 这是一个单用户可运行实现,不是完整 Mastodon 服务端:
 
 - 只支持单管理员账号自动初始化,不开放注册
-- 通知 / 收藏 / 转发都已实现,但内容审核、屏蔽、过滤、列表、自定义表情、推送通知仍是 stub
-- 没有处理远端嘟文缓存(收到 `Create(Note)` 不会存,仅触发提及通知)。意味着客户端的 home timeline 仍只能看到本地嘟文
+- 远端嘟文缓存只在被本地账号关注的 actor 发出的 `Create(Note)` 时写入,不抓取历史 outbox
+- `media_attachments` 已缓存(URL 指向远端原始域名),但 `mentions`、`tags` 在远端缓存嘟文中是空数组
 - 私信(direct visibility)的检索没有按收信人过滤,目前所有客户端都能在公开时间线之外读到自己的嘟文,不应当作私信使用
 - 没有实现轮询(poll)、列表(list)、推送(push)、未来嘟文(scheduled)等