ActivityPub

一个基于 Fedify 构建的多租户 ActivityPub 服务器，用于 Ghost。该服务使独立网站能够直接将内容发布到 Fediverse，实现向开放社交网络的网络发布。

本地开发运行

所有发往 /.ghost/activitypub/*、/.well-known/webfinger 和 /.well-known/nodeinfo 的请求通过 nginx 代理到该 ActivityPub 服务。其他所有请求则转发到 Ghost。此设置仅在 macOS 上使用 Docker for Mac 和 OrbStack 进行过测试。

安装步骤

1. 安装 Ghost，使用“从源码安装”说明
2. **使用 Tailscale（或 *）暴露本地 80 端口（nginx）
   • 使用 tailscale funnel 80 或 ngrok http 80 暴露本地80 端口（不是 2368！），nginx 将在此端口运行
3. 配置 Ghost
   • 在 Ghost monorepo 中，在 ghost/core/config.local.json 路径下创建 config.local.json 文件，配置如下：

{
   "url":
   }

4. 启动 ActivityPub 服务
   • 在本项目根目录运行 yarn dev && yarn logs
5. 启动 Ghost
   • 在 Ghost monorepo 中运行 yarn dev
   • 如果已在本地运行 Ghost，确保重启它！

🏗️ 架构与开发指南

[!NOTE] AI 助手参考：详见 AGENTS.md，包含完整代码示例指导。
开发者参考：详见 /adr 目录中的架构决策记录，了解详细设计 rationale。

核心架构模式

本服务遵循领域驱动设计（Domain-Driven Design），并采用以下特定模式：

• 带事件的不可变实体 (ADR-0003) - 实体返回包含领域事件的新实例
• 结果类型模式 (ADR-0004) - 使用 Result 类型进行显式错误处理
• 结果中的错误对象 (ADR-0005) - 增强的 Result 类型，包含上下文错误对象
• 基于类的架构 (ADR-0006) - 所有组件使用带依赖注入的类
• 仓库模式 (ADR-0007) - 服务编排业务逻辑，仓库处理数据访问
• 读取视图模式 (ADR-0008) - 优化的读取查询与写入路径分离
• 基于哈希的查找 (ADR-0009) ⚠️ - ActivityPub ID 使用 SHA256 哈希
• 装饰器路由 (ADR-0010) - 通过装饰器定义路由

项目结构

src/
├── account/ # 不可变实体
├── post/ # 正在迁移为不可变实体
├── activity-handlers/ # 基于类的处理器
├── http/api/ # REST 控制器
├── core/ # 共享工具
└── dispatchers.ts # 遗留文件 - 不要在此添加内容

⚠️ 关键注意事项

[!WARNING] 1. 数据库查找必须使用 SHA256 哈希 (ADR-0009)

• 禁止使用 where('ap_id', apId) - 它会静默返回空结果！
• 必须使用 whereRaw('ap_id_hash = UNHEX(SHA2(?, 256))', [apId])
• 适用于：ap_id、domain（需配合 LOWER）、ap_inbox_url（需配合 LOWER）

[!IMPORTANT] 2. 结果类型需使用辅助函数

• 使用 isError(result)、getValue(result)、getError(result)
• 禁止直接解构，如 [error, value]

[!IMPORTANT] 3. 服务必须使用仓库

• 视图可直接查询数据库（读取优化）
• 服务必须通过仓库访问数据（写入路径）

[!IMPORTANT] 4. 依赖注入名称必须匹配

• 参数 accountService → 注册为 'accountService'
• 参数 db → 注册为 'db'

[!WARNING] 5. 避免以下反模式

• 向 dispatchers.ts 添加内容 → 应创建新的处理器类
• 使用 AccountType → 应使用 Account 实体
• 在服务中直接查询数据库 → 应使用仓库
• 对 AP ID 进行字符串比较 → 应使用哈希查找

有关演示正确模式的完整代码示例，请参见 AGENTS.md。

代码格式化与 linting

我们使用 Biome 进行代码格式化和 linting。

如果使用 VS Code，可安装 Biome 扩展获取行内反馈。

要启用保存时自动格式化，需将默认格式化程序设置为 Biome 并在 VS Code 设置中启用 Format on Save。

运行测试

• 运行 yarn test 在 Docker Compose 环境中执行测试。

数据库迁移

docker compose run migrate 或 docker compose run migrate-testing 分别针对开发或测试数据库运行 up 迁移。

如需运行其他命令，可执行 docker compose exec -it migrate /bin/bash 或 docker compose exec -it migrate-testing /bin/bash - 这将进入包含 migrate 二进制文件的 shell，同时提供 MYSQL_DB 环境变量，其格式适用于作为 migrate 二进制文件的 -database 参数。

版权与许可

Copyright (c) 2013-2026 Ghost Foundation - 基于 MIT 许可发布。Ghost 及 Ghost 徽标是 Ghost Foundation Ltd. 的商标。有关可接受使用方式的信息，请参见我们的商标政策。