中文 | English
不懂代码、不会运维也能用。 租一台服务器，跟着 AI 一步步复制粘贴命令就能部署上线；日常只需打开浏览器点点鼠标，就能管理多个网站的内容。面向零代码用户、独立开发者，以及希望让 AI Agent 自动维护内容的人。
面向 Agent 的无头内容管理系统（Agent-Ready Headless CMS）：一套后台管理多站点，内置用户/会员体系、支付订单、内容访问控制，并为外部 AI Agent 提供 API / MCP 内容接口（按 Key scope 授权）。
内容采用「草稿 → 提交审核 → 人工审核 → 发布」工作流。Agent 默认只读取内容、创建/编辑草稿、上传媒体、提交审核、查看版本历史；发布与删除仅在 API Key 的 scope 显式授予 publish / delete_content 时才可用（owner 决策，见 @agentcms/shared 的 AgentAllowedAction），未授予的 Key 无法发布或删除。Agent 始终不能改动用户/会员/订单/支付。所有 Agent 操作均记审计日志。
- 多站点管理：单后端实例服务多个站点，基于 PostgreSQL
tenant_id多租户隔离。 - 内容模型：内容模型字段用 JSONB 动态定义，支持分类、标签。
- 内容访问控制：公开 / 登录可见 / 会员可见 / 指定套餐 / 付费 / 密码保护。
- 用户与会员体系：前台用户注册登录、会员套餐、订单。
- 支付：手动确认（manual）、Alipay、Stripe、通联收银宝（SYB H5 收银台）；各网关凭据按站点在后台加密配置（AES-256-GCM 落库）。
- 后台权限（RBAC）：超级管理员、站点管理员、编辑、作者、客服、Agent 等角色与权限管理。
- Agent / MCP 接口：外部 Agent 通过 API Key 操作内容（按 Key scope 授权：读取/草稿/提交审核/版本/媒体，可选发布与删除）；同时提供标准 MCP Server 供 AI 工具接入。
- 审核与审计：内容审核流、版本记录、操作日志。
- 媒体存储：本地磁盘或 Cloudflare R2（S3 兼容），二选一自动切换。
| 层 | 技术 |
|---|---|
| 运行时 | Node.js（>=20）+ TypeScript，全栈 |
| 后端 | Hono、Drizzle ORM、PostgreSQL、Redis、BullMQ |
| 前端（admin） | React 18 + Vite、Ant Design 5、Zustand、TanStack Query、React Router v6 |
| 鉴权 | 自定义 JWT + refresh token |
| 存储 | Cloudflare R2（S3 兼容），未配置时回退本地磁盘 |
| 支付 | Alipay SDK、Stripe SDK、通联收银宝，手动确认通道；网关凭据按站点加密存储 |
| MCP | @modelcontextprotocol/sdk |
| 邮件 | Nodemailer；SMTP 按站点在后台配置，未配置时回退控制台输出 |
| 日志 | Pino（结构化 JSON） |
| 部署 | Docker Compose + Caddy（反向代理、自动 HTTPS） |
| i18n | react-i18next（admin 界面），内容含 locale 字段，时间统一 UTC 存储 |
pnpm workspace 单体仓库（无 Turborepo/Nx），三个包：
agentcms/
├── packages/
│ ├── server/ # Hono 后端：REST API + MCP Server + Drizzle 模型/服务层
│ ├── admin/ # React 管理端（Vite + Ant Design 5）
│ └── shared/ # 跨包 TypeScript 类型与常量（API 契约、枚举、权限）
├── drizzle/ # 数据库迁移文件
├── docker-compose.yml # 本地开发：PostgreSQL + Redis
├── docker-compose.prod.yml # 生产：Postgres + Redis + server + Caddy
└── package.json # pnpm workspace 根
跨包类型一律放 packages/shared，server 与 admin 都从 @agentcms/shared 导入。
全部为 RESTful JSON，统一响应信封（无 GraphQL）。
| 层 | 路由前缀 | 认证 | 用途 |
|---|---|---|---|
| Public API | /api/public |
无 / 可选 JWT | 前台网站消费、内容访问判断 |
| Admin API | /api/admin |
JWT | 后台管理 |
| Agent API | /api/agent |
API Key | 外部 Agent 内容操作 |
| MCP Interface | /api/mcp |
MCP 协议 | 标准 MCP Server（AI 工具接入） |
健康探针：GET /healthz（存活）、GET /readyz（就绪，检查 PostgreSQL + Redis，不可用时返回 503）。支付回调：/api/payment/webhook/*。
前置：Node.js >= 20、pnpm >= 9、Docker。
# 1. 安装依赖
pnpm install
# 2. 准备环境变量
cp .env.example .env # 按需修改；开发默认值开箱即用
# 3. 启动本地基础设施（PostgreSQL + Redis）
docker-compose up -d
# 4. 运行数据库迁移
pnpm --filter server db:migrate
# 5. 写入种子数据（默认站点 + 超级管理员）
pnpm --filter server db:seed
# 6. 分别启动后端与管理端（两个终端）
pnpm --filter server dev # 后端，默认 http://localhost:3000
pnpm --filter admin dev # 管理端，http://localhost:5173（API 走代理）开发种子默认账号（仅开发环境）：超级管理员 admin@agentcms.local / admin12345。生产环境会拒绝使用该默认密码，见下文安全注意。
常用命令：
pnpm --filter server db:generate # 生成 Drizzle 迁移
pnpm --filter server db:studio # Drizzle Studio（数据库浏览器）
pnpm build # 构建所有包（pnpm -r build）
pnpm lint # ESLint
pnpm format # Prettier 写入面向没有运维经验的人：在一台全新的 Linux 服务器上，从零到能用，只有三步。把下面的命令逐段粘贴进服务器终端即可（不懂某一步就把它连同报错一起发给 AI，让它带你做）。
# 1. 装 Docker（已装可跳过）
curl -fsSL https://get.docker.com | sh
# 2. 下载本程序
git clone https://github.com/allinopc/agentcms.git agentcms && cd agentcms
# 3. 运行安装向导（会自动检查环境、生成所有密钥）
./install.sh向导只问你几个问题：超级管理员邮箱 / 密码、站点域名（填真实域名即自动开 HTTPS，没有就填 :80 用 IP 访问）、支付回调地址、可选 CORS。其余全部密钥自动生成（Postgres / Redis 密码、JWT / refresh / API Key 密钥、AES 加密密钥），无需手填。
跑完后浏览器打开你填的域名（或 http://服务器IP）登录即可。支付与邮件不在命令行配 —— 登录后台后在「设置 → 支付设置 / 站点设置」里按站点填写（凭据加密存库，见下文）。
环境缺 Docker 时，向导会先停下并告诉你怎么装，不会跑到一半崩。 已有
.env时会先备份成.env.bak.<时间戳>再覆盖，不会静默丢失。 想先看生成的.env而不启动：./install.sh --print-env。
若需自定义编排，可直接用 docker-compose.prod.yml：包含 Postgres、Redis（内网、强制密码、不暴露端口）、server（启动时自动跑迁移再监听）、Caddy（托管 admin SPA + 反向代理 + 自动 HTTPS）。仅 Caddy 对外暴露 80/443 端口。
cp .env.example .env # 手动填入生产密钥与 SITE_ADDRESS（或用 install.sh 生成）
docker compose -f docker-compose.prod.yml up -d --build用
install.sh部署时，下面这些密钥全部自动生成，无需手填。本表供手动部署或排查时参考。
docker-compose.prod.yml 中带 ${VAR:?} 的变量为必填，未设置会导致启动失败。
| 变量 | 说明 | 是否必填 |
|---|---|---|
POSTGRES_PASSWORD |
PostgreSQL 密码 | 必填 |
POSTGRES_USER |
PostgreSQL 用户（默认 agentcms） |
可选 |
POSTGRES_DB |
数据库名（默认 agentcms） |
可选 |
REDIS_PASSWORD |
Redis 密码（生产强制） | 必填 |
JWT_SECRET |
访问令牌签名密钥（生产 ≥ 32 字符） | 必填 |
REFRESH_TOKEN_SECRET |
刷新令牌签名密钥（生产 ≥ 32 字符） | 必填 |
API_KEY_SALT |
Agent API Key 哈希盐（生产 ≥ 32 字符） | 必填 |
APP_ENCRYPTION_KEY |
32 字节密钥（hex 或 base64），AES-256-GCM 加密落库密钥（按站点配置的支付 / SMTP 凭据）；配置这些功能时必需 | 必填 |
SEED_SUPER_ADMIN_PASSWORD |
生产种子超级管理员密码（≥ 12 字符），跑 db:seed 时必需 |
跑 seed 时必填 |
SEED_SUPER_ADMIN_EMAIL |
生产种子超级管理员邮箱 | 可选 |
SITE_ADDRESS |
Caddy 站点地址；填真实域名启用自动 HTTPS，本地/预发用 :80（默认 :80） |
可选 |
CORS_ORIGINS |
允许的 CORS 源，逗号分隔；默认 *，生产应设显式白名单 |
可选 |
AUTH_RATE_LIMIT_MAX |
登录/凭据端点每 IP 每分钟请求上限（防爆破）；默认 10，仅在受信环境（如 E2E 后端）调高 | 可选 |
PAYMENT_BASE_URL |
本后端公网地址，用于拼接支付回调 URL，需支付网关可达 | 可选 |
凭据全部在后台配置，不碰 env：支付凭据（Stripe / Alipay / 通联收银宝）和各站点 SMTP 邮件，均在后台管理界面录入，用
APP_ENCRYPTION_KEY做 AES-256-GCM 加密后落库（tenant_*_configs表）。没有任何 SMTP / 支付 env 变量。站点未配置 SMTP 时，验证 / 重置邮件打印到控制台（不静默丢弃）。本产品面向非技术用户，配置环境变量不友好，因此凭据一律走后台 UI。
server 容器内 DATABASE_URL、REDIS_URL 由上述变量自动拼装；MEDIA_STORAGE_DIR 固定为 /data/media（持久卷）。
测试框架为 Vitest 2，测试与源码同目录（*.test.ts(x)）。
pnpm test # 全仓所有包
pnpm --filter @agentcms/server test # 仅 server
pnpm --filter @agentcms/admin test # 仅 admin
pnpm --filter @agentcms/admin test:e2e # admin Playwright E2E集成测试约束：
- 需要真实 PostgreSQL。
NODE_ENV=test下 server 读TEST_DATABASE_URL，且该 URL 必须包含子串test（防误连 dev / 生产库，配置层强制校验）。 - 跑集成测试前先执行迁移：
NODE_ENV=test pnpm --filter @agentcms/server db:migrate。 - server 的
vitest.config.ts关闭文件并行（fileParallelism:false+singleFork）：集成测试共享一个 test 库，串行执行避免跨文件 truncate 竞争。
真实浏览器 E2E（Playwright，真实 Chromium 点击全部后台页面）需要一个运行中的后端。最简单的方式是起一套隔离的生产镜像栈（与开发/生产数据互不影响）：
# 1. 起隔离栈（独立项目名 agentcms-e2e，server 暴露在 host :3030）
docker compose -p agentcms-e2e --env-file .env.e2e \
-f docker-compose.prod.yml -f docker-compose.e2e.yml up -d
# 2. 种入已知凭据的超管（见 .env.e2e 的 SEED_SUPER_ADMIN_*）
docker exec agentcms-e2e-server-1 sh -c 'cd /app/packages/server && node dist/db/seed/index.js'
# 3. 跑 Playwright，指向该后端
pnpm --filter @agentcms/admin test:e2e:install # 一次性：装 Chromium
VITE_API_PROXY_TARGET=http://127.0.0.1:3030 \
E2E_ADMIN_EMAIL=... E2E_ADMIN_PASSWORD=... \
pnpm --filter @agentcms/admin test:e2e
# 4. 用完拆栈（连卷一起删）
docker compose -p agentcms-e2e -f docker-compose.prod.yml -f docker-compose.e2e.yml down -v- 生产密钥（
JWT_SECRET、REFRESH_TOKEN_SECRET、API_KEY_SALT）必须 ≥ 32 字符随机值，配置层在NODE_ENV=production下强制校验。 - 切勿使用开发默认弱密码：生产
db:seed要求SEED_SUPER_ADMIN_PASSWORD≥ 12 字符，否则拒绝执行。 - Redis 在生产 compose 中强制密码、仅限内网、不对外暴露端口。
- 邮件（邮箱验证、密码重置）在后台按站点配置 SMTP，无 SMTP env 变量；站点未配置时邮件仅打印到控制台（不真正发送）。面向非技术用户，配置全程在后台 UI 完成。
- 配置按站点加密的支付 / SMTP 凭据时必须设置
APP_ENCRYPTION_KEY（32 字节，AES-256-GCM 落库加密）；生产 compose 已标记为必填。 - 生产应设置显式
CORS_ORIGINS白名单，不要保留默认*。 - 切勿提交
.env，仅提交.env.example。
本项目采用 AGPL-3.0-only 开源协议 © 2026 hechenzhou。
AGPL-3.0 的核心：任何人修改本软件并以网络服务（SaaS）形式提供，必须向其用户公开完整的修改后源码。
个人自用、学习、内部部署遵循 AGPL-3.0 即可，免费。以下场景欢迎邮件联系 335509995@qq.com：
- 商业授权：在闭源产品中使用，或不愿受 AGPL 传染条款约束 —— 购买商业授权可豁免 AGPL 义务。
- 技术支持 / 部署服务：付费协助安装、上线、运维，或私有化定制部署。
- 定制开发：按需开发功能、对接第三方系统（支付、短信、第三方登录等）。
- OEM / 贴牌：白标分发、二次销售。
- 托管版（SaaS）合作：等托管版上线后的渠道、代理、分成合作。
- 贡献指南见 CONTRIBUTING.md。
设计文档与管理端界面文本为中文；代码、注释、提交信息、API 响应使用英文。