ghcr.io/tryghost/activitypub:sha-c19d0b0

ActivityPub

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

本地开发运行

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

设置

• 按照《从源码安装》（Install from source）说明安装Ghost
• 使用Tailscale（或***）暴露本地80端口（nginx）。使用tailscale funnel 80或ngrok http 80暴露本地80端口（不是2368！），nginx将在此端口运行
• 配置Ghost。在Ghost monorepo中，在ghost/core/config.local.json路径下创建config.local.json文件，包含以下配置：

{
"url":
}

• 启动ActivityPub服务。在本项目的根目录中运行pnpm dev && pnpm logs
• 启动Ghost。在Ghost monorepo中运行pnpm dev。如果您已在本地运行Ghost，请确保重启它！

🏗️ 架构与开发指南

[!NOTE] 对于AI助手：请参阅AGENTS.md获取包含代码示例的综合指南。对于开发人员：请参阅/adr目录中的架构决策记录（Architecture Decision Records）了解详细原理。

核心架构模式

本服务遵循领域驱动设计（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 # 遗留文件 - 不要在此添加内容

⚠️ 关键注意事项

1. 数据库查找必须使用SHA256哈希（ADR-0009）

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

2. 结果类型需要辅助函数

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

3. 服务必须使用仓储

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

4. 依赖注入名称必须匹配

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

5. 避免以下反模式：

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

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

代码格式化与 linting

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

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

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

运行测试

测试在Docker Compose栈中运行。常用命令：

• pnpm test — 运行所有测试（类型检查、单元测试、集成测试和端到端测试）；速度较慢
• pnpm test:unit — 仅运行单元测试；速度快
• pnpm test:integration — 仅运行集成测试
• pnpm test:cucumber — 端到端（Cucumber）测试
• pnpm test:single 'path/to/test' — 运行单个单元或集成测试
• pnpm test:types — 使用tsc进行类型检查

完整命令列表和测试约定请参阅AGENTS.md。

迁移

运行pnpm migrate以将待处理的向上迁移应用于开发数据库（pnpm dev时也会自动执行）。对于测试数据库，使用docker compose run migrate-testing up。

要运行其他迁移命令，可通过docker compose exec -it migrate /bin/sh（或migrate-testing）进入shell。迁移二进制文件（migrate）在此处可用，同时提供正确格式的MYSQL_DB环境变量，可用于-database参数。

版权与许可

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

🏗️ 架构与开发指南

面向 AI 助手： 详见 AGENTS.md，包含带代码示例的全面指导。 面向开发人员： 详见 /adr 目录中的架构决策记录，了解详细设计 rationale。

核心架构模式

本服务遵循领域驱动设计，并采用以下特定模式：

• 带事件的不可变实体（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 # 遗留文件 - 请勿在此添加内容

⚠️ 关键注意事项

[!IMPORTANT] 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'

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

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

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

代码格式化与 linting

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

如果使用 VS Code，可安装 https://marketplace.visualstudio.com/items?itemName=biomejs.biome 获取行内反馈。

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

运行测试

测试在 Docker Compose 环境中运行。常用命令：

• pnpm test — 运行所有测试（类型检查、单元测试、集成测试和端到端测试）；速度较慢
• pnpm test:unit — 仅运行单元测试；速度较快
• pnpm test:integration — 仅运行集成测试
• pnpm test:cucumber — 运行端到端（Cucumber）测试
• pnpm test:single 'path/to/test' — 运行单个单元测试或集成测试
• pnpm test:types — 使用 tsc 进行类型检查

完整命令列表和测试约定详见 AGENTS.md。

数据库迁移

运行 pnpm migrate 可将待处理的 up 迁移应用到开发数据库（pnpm dev 时也会自动执行此操作）。对于测试数据库，使用 docker compose run migrate-testing up。

要运行其他 migrate 命令，可通过 docker compose exec -it migrate /bin/sh（或 migrate-testing）进入 shell。其中提供 migrate 二进制工具，以及格式化为 -database 参数所需的 MYSQL_DB 环境变量。

 

版权与许可

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