内容
<div align="center">
<img src="frontend/public/icon-192.png" width="96" alt="goloom logo" />
# goloom
**轻量级、自托管的社交媒体规划工具，适用于团队和AI代理。**
在Mastodon、Bluesky和Friendica上规划帖子，只需一个Go二进制文件 - 无需企业级堆栈，无需按席位定价。
<!-- Build & tech -->
[](https://github.com/Goloom-App/goloom/actions/workflows/pages.yml)
[](go.mod)
[](frontend)
[](#deployment-options)
[](#docker)
[](#api-documentation)
[](frontend/playwright.config.ts)
[](LICENSE)
<!-- Repository activity -->
[](https://github.com/Goloom-App/goloom/commits/main)
[](https://github.com/Goloom-App/goloom/issues)
[](https://github.com/Goloom-App/goloom/pulls)
[](https://github.com/Goloom-App/goloom/stargazers)
<br />
<img src="website/src/assets/screenshots/content-calendar.png" alt="goloom 内容日历" width="820" />
</div>
---
`goloom` 是一个自托管的社交媒体规划应用程序，构建为一个Go二进制文件（API + Web UI）。它帮助团队在多个社交账户上规划帖子，无需复杂的企业级基础设施和定价模型。
## 为什么存在goloom
这个领域的多数工具都很强大，但也很复杂：复杂的堆栈，许多付费层级，以及针对大型组织的优化产品范围。
goloom的创建是为了实现一个专注的结果：
- 在不同的社交媒体账户上规划帖子
- 在团队中协作
- 保持操作简单
- 与OpenClaw等AI代理集成
## 截图
<table>
<tr>
<td width="50%"><img src="website/src/assets/screenshots/composer.png" alt="帖子编辑器，实时预览" /></td>
<td width="50%"><img src="website/src/assets/screenshots/analytics.png" alt="团队绩效分析" /></td>
</tr>
<tr>
<td align="center"><strong>编辑器</strong> — 一次编写，跨平台预览</td>
<td align="center"><strong>分析</strong> — 参与度和关注者趋势</td>
</tr>
</table>
## 亮点
- 单二进制文件部署：UI和API在一个进程中。
- 默认使用SQLite：无需外部数据库。
- 可选PostgreSQL适用于较大部署。
- 团队工作区，成员角色（`owner`、`editor`、`viewer`）。
- 调度、验证、每个账户的帖子版本、媒体库。
- 内置分析功能，帖子和账户指标。
- API优先架构，带有Bearer令牌身份验证。
- OIDC支持浏览器登录。
- Mastodon注册可以自动从实例URL注册应用程序凭证。
## 入门指南
三种运行goloom的方式 - 选择一种（完整指南：
[安装](https://goloom-app.github.io/getting-started/installation/))：
- **Docker** — `docker run ... ghcr.io/goloom-app/goloom:latest` （参见 [Docker](#docker)）。
- **预编译二进制文件** — 从
[最新版本](https://github.com/Goloom-App/goloom/releases/latest)
（`goloom_<version>_linux_amd64` / `arm64`）下载静态Linux二进制文件，`chmod +x`，设置 `ENCRYPTION_KEY` +
`BOOTSTRAP_ADMIN_TOKEN` 并运行它。Web UI嵌入其中；默认情况下数据存储在
`./data/goloom.db`（SQLite）中。
- **从源代码** — 自己构建（下面）。
### 1) 配置环境
```bash
cp .env.example .env
```
设置必填值：
```bash
ENCRYPTION_KEY=替换为一个长随机密钥
BOOTSTRAP_ADMIN_TOKEN=替换为一个强启动令牌
```
### 2) 构建和运行
```bash
make build
./bin/goloom
```
打开 [http://localhost:8080](http://localhost:8080)。
### 3) 引导第一个管理员访问
在UI设置屏幕中使用启动令牌。首次登录后，创建常规API令牌并轮换启动密钥。
## API文档
goloom API设计用于开发人员和AI代理。
专业文档堆栈使用OpenAPI + Redocly。
### 基本路径
- 主要：`/v1/...`
- 别名：`/api/v1/...`（相同的处理程序，适用于期望 `/api/v1` 的工具）
### 身份验证
使用Bearer令牌：
```http
Authorization: Bearer <oidc-id-token-or-api-token>
```
### API快速入门（curl）
健康和身份验证状态：
```bash
curl -s http://localhost:8080/healthz
curl -s http://localhost:8080/v1/auth/status
```
列出提供程序：
```bash
curl -s http://localhost:8080/v1/providers
```
获取当前身份：
```bash
curl -s \
-H "Authorization: Bearer $TOKEN" \
http://localhost:8080/v1/me
```
### 端点组
- 发现：`/healthz`，`/v1/providers`，`/v1/auth/status`
- 身份：`/v1/me`，`/v1/me/api-tokens`
- 团队：`/v1/teams`，`/v1/teams/{teamID}/members`
- 账户：`/v1/teams/{teamID}/accounts`，OAuth启动端点
- 帖子：`/v1/teams/{teamID}/posts`，验证，版本，取消
- 分析：`/v1/teams/{teamID}/analytics*`，帖子分析
- 管理：`/v1/admin/*`，提供程序实例管理
有关完整的路由列表，请参见 `api/http.go`。
### API文档
交互式API参考使用 [Scalar](https://scalar.com) 渲染，并由网站在 `/api/` 提供。它直接读取OpenAPI规范，因此没有单独的静态构建步骤。
校验OpenAPI规范：
```bash
make docs-api-lint
```
- 源规范：`docs/api/openapi.yaml`（单一真实来源）
- 规范复制到 `website/public/openapi.yaml` 由 `make website-build`
### AI代理集成说明（OpenClaw和类似）
- 内置 **MCP服务器** （可流式HTTP传输）位于 `/mcp`（默认启用，`MCP_ENABLED`），使用带有 `read` / `write:draft` / `write:schedule` / `write` / `delete` 作用域的API令牌进行身份验证（无作用域令牌具有完全访问权限）。
- 核心端点的稳定JSON响应。
- 具有团队作用域对象的可预测资源路径。
- 调度前验证端点：`POST /v1/teams/{teamID}/posts/validate`。
- 用于安全代理入站的API令牌生命周期端点。
## 网站和文档
项目网站（Astro + Starlight）位于 `website/`：一个营销登陆页面，文档（3列Starlight布局）和 `/api/` 处的Scalar API参考。
本地开发服务器：
```bash
make website-dev
```
构建静态站点（包括API文档）：
```bash
make website-build
```
生成的输出：`website/dist/`
通过推送到 `main` 时部署到GitHub Pages，当 `website/` 或 `docs/api/` 更改时：[`pages.yml`](.github/workflows/pages.yml) 工作流使用 `make website-build` 构建站点，并强制推送 `website/dist` 到组织Pages仓库
[`goloom-app.github.io`](https://github.com/Goloom-App/goloom-app.github.io)，GitHub在根URL
[https://goloom-app.github.io/](https://goloom-app.github.io/) 提供服务。
## 提供程序支持
### Mastodon
- OAuth账户连接
- 可选的实例URL自动应用程序注册
- 发布和指标（`likes`、`reposts`、`replies`）
### Friendica
- 手动提供程序应用程序凭证
- 发布和Mastodon兼容的指标
### Bluesky
- 账户连接，应用密码
- 发布和指标支持
## 部署选项
### 默认（单二进制文件 + SQLite）
适用于低运维环境和小到中型团队。
```bash
DATABASE_URL=file:./data/goloom.db
```
### PostgreSQL
当您需要外部DB操作和扩展模式时使用：
```bash
DATABASE_URL=postgres://postgres:postgres@localhost:5432/goloom?sslmode=disable
```
升级PostgreSQL到新的 **主要** 版本（例如16 → 18）是转储和
恢复，而不是就地交换 - 请参阅
[PostgreSQL主要升级指南](https://goloom-app.github.io/migrations/postgres-major-upgrade/).
### Kubernetes (Helm)
Helm图表位于 [`deploy/helm/goloom`](deploy/helm/goloom)（SQLite在
持久卷上，或外部PostgreSQL；可选Ingress）：
```bash
helm install goloom ./deploy/helm/goloom \
--namespace goloom --create-namespace \
--set secret.encryptionKey="$(openssl rand -hex 32)" \
--set secret.bootstrapAdminToken="change-me-please" \
--set config.publicBaseUrl="https://goloom.example.com"
```
参见 [Kubernetes（Helm）指南](https://goloom-app.github.io/getting-started/kubernetes/)。
## 生产迁移（Docker → Kubernetes）
如果您使用Docker PostgreSQL并希望迁移到homelab CNPG部署，请参见 [`docs/migrations/docker-to-kubernetes-homelab.md`](docs/migrations/docker-to-kubernetes-homelab.md)。
## Docker
使用发布的multi-arch镜像（linux/amd64 + arm64）从GHCR：
```bash
docker run --rm \
-p 8080:8080 \
-e ENCRYPTION_KEY=替换为一个长随机密钥 \
-e BOOTSTRAP_ADMIN_TOKEN=替换为一个强启动令牌 \
-v "$(pwd)/data:/app/data" \
ghcr.io/goloom-app/goloom:latest
```
对于生产环境，请固定版本标签（例如 `ghcr.io/goloom-app/goloom:v0.1.0`）
而不是 `:latest`。自己构建镜像：`docker build -t goloom .`。
## 开发
```bash
nix develop
make run
```
前端开发服务器：
```bash
make frontend-dev
```
CI中推荐的API文档工作流：
- 在拉取请求上运行 `make docs-api-lint` 以验证OpenAPI规范
- 参考文档作为网站的一部分发布（`make website-build`)
## 配置
从 `.env.example` 开始。常见键：
- `APP_ENV`、`HTTP_ADDR`、`PUBLIC_BASE_URL`
- `DATABASE_URL`
- `ENCRYPTION_KEY`
- `BOOTSTRAP_ADMIN_*`
- `SCHEDULER_*`
- `OIDC_*`
- `MASTODON_*`
## 与重型平台相比
goloom故意优化：
- 较低的运行时开销
- 更容易的自托管
- 实用的团队协作
- 适用于代理工作流的API优先自动化
如果您需要广泛的企业套件，许多商业增值模块或高级活动生态系统，其他产品可能更适合。如果您需要一个专注的调度器，具有强大的API人体工程学和简单的操作，goloom就是目标形状。
## 安全说明
- 提供者访问令牌存储时加密。
- API令牌存储为哈希值。
- 设置强 `ENCRYPTION_KEY` 并在设置后轮换启动/管理员密钥。
## 版本控制和发布
goloom遵循 [Semantic Versioning](https://semver.org/) 并故意
**pre-1.0（0.x）** — 今天可用且可自托管，但重大更改仍可能
在次要版本之间发生，因此固定版本并在升级前阅读说明。
- 版本由 [Conventional Commits](https://www.conventionalcommits.org/)
通过 [release-please](https://github.com/googleapis/release-please) 自动发布：发布PR
维护 `CHANGELOG.md` 和版本；合并后标记 `vX.Y.Z`，发布
[GitHub Release](https://github.com/Goloom-App/goloom/releases) 带有预编译
Linux二进制文件（amd64/arm64），并推送 `ghcr.io/goloom-app/goloom` 镜像。
- 运行版本由 `GET /healthz` 和代理发现文档报告。
- REST API在其 `/v1` 下有自己的版本合约，与应用版本无关；
仅在发生破坏性API更改时更改。
## 关于这个项目
goloom源于我自己作为自托管工具的需求。它是用大量AI构建的，我用它作为探索高效、AI辅助开发方法的测试平台。
## 许可证
在 [MIT License](LICENSE) 下许可。
