ActivityPub

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

本地开发运行

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

/.ghost/activitypub/* /.well-known/webfinger /.well-known/nodeinfo

安装配置

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

{
"url":
}

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

🏗️ 架构与开发指南

[!NOTE] AI助手：请参阅AGENTS.md获取包含代码示例的全面指南。开发人员：请参阅 /adr 中的架构决策记录了解详细原理。

AI助手：请参阅AGENTS.md获取包含代码示例的全面指南。开发人员：请参阅 /adr 中的架构决策记录了解详细原理。

/adr

核心架构模式

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

• 带事件的不可变实体（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) - 它会静默返回空结果！ where('ap_id', apId)
• 始终使用 whereRaw('ap_id_hash = UNHEX(SHA2(?, 256))', [apId]) whereRaw('ap_id_hash = UNHEX(SHA2(?, 256))', [apId])
• 适用于：ap_id、domain（带LOWER）、ap_inbox_url（带LOWER） ap_id domain ap_inbox_url

[!WARNING] 2. 结果类型需要辅助函数

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

[!WARNING] 3. 服务必须使用仓储

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

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

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

[!WARNING] 5. 避免这些反模式：

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

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

代码格式化与Linting

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

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

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

Biome Format on Save

运行测试

• 运行 yarn test 在Docker Compose堆栈中执行测试。 yarn test

迁移

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

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 - 这将进入一个shell，其中包含 migrate 二进制文件以及格式正确的 MYSQL_DB 环境变量，可用作 migrate 二进制文件的 -database 参数。

docker compose exec -it migrate /bin/bash docker compose exec -it migrate-testing /bin/bash migrate MYSQL_DB -database migrate

版权与许可

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

---

项目仓库 README（补充）

 

 

ActivityPub

适用于Ghost的多租户ActivityPub服务器，基于Fedify构建。此服务使独立网站能够将其内容直接发布到联邦宇宙（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 中的架构决策记录了解详细原理。

核心架构模式

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

• 带事件的不可变实体 (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。

运行测试

• 运行 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 - 这将进入一个shell，其中包含 migrate 二进制文件以及格式正确的 MYSQL_DB 环境变量，可用作 migrate 二进制文件的 -database 参数。

 

版权与许可

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