WooCMS 开发者文档

本页基于当前仓库源码与 docs 文档整理，覆盖架构、启动、开发流程、扩展机制与运维检查点，适用于 WooCMS v3 Go 架构。

本地启动

建议优先使用 Make 目标。开发环境使用 make run 或 make dev，生产环境使用面板托管的固定二进制启动脚本。

# 1) 初始化环境变量
cp .env.example .env

# 2) 本地开发（任选其一）
make run
# 或
make dev

# 3) 测试与质量检查
make test
make fmt
make lint

启动后可用以下地址验证：/livez、/readyz、/healthz、/metrics、/admin/login。

标准开发流程

1. 先阅读并对齐 docs/DEVELOPMENT_STANDARDS.md。
2. 新增行为优先落在 internal/domain/*/service.go，保持 Handler 薄层。
3. 涉及 schema 变更必须新增成对 migration（up/down）。
4. 写操作遵循：CSRF 校验 → Service 调用 → 审计日志。
5. 完成后执行测试/构建，并更新 docs/PROGRESS_LOG.md。

目录结构与职责

cmd/admin/                 # 程序入口，装配配置/数据库/缓存/路由
internal/httpserver/       # router + handlers + middleware
internal/domain/*/         # 业务域服务（auth/content/page/media/plugin/theme...）
internal/repo/pg/          # PostgreSQL 连接池与慢查询跟踪
internal/cache/            # Redis 封装与缓存键
migrations/                # 数据库迁移脚本（必须 up/down 成对）
web/templates/             # 后台 SSR 模板
web/themes/                # 前台主题模板与资源
docs/                      # 规范、计划、日志、安装与开发文档

启动入口与依赖装配

程序入口在 cmd/admin/main.go：读取配置、初始化 PostgreSQL 与 Redis、启动定时任务（发布任务与 Webhook 分发），最后通过 httpserver.NewRouter 挂载路由并启动 HTTP 服务。

路由入口在 internal/httpserver/router.go：统一注册中间件、健康检查、前台路由、后台权限路由，以及安装向导与升级入口。

请求与权限链路

• 每个请求都注入 X-Request-ID 并输出结构化日志。
• SiteContextMiddleware 从 query/header/form 解析站点上下文。
• 后台路由默认链路：authRequired → permissionRequired(InSite) → 业务 Handler。
• 演示账号写操作由 readOnlyUserWriteBlocker 阻断。

领域服务分层约定

核心业务按 bounded context 组织在 internal/domain/，例如：

• content：文章、版本、工作流、调度发布。
• page：页面模型与发布。
• media：上传、分组、元数据、上下文引用。
• plugin：插件生命周期、Hook、观测与告警。
• theme：主题版本、激活、回滚、同步。

插件系统与 Hook 开发

当前插件模式为上传型 ZIP（非编译型），默认目录 plugins/packages。插件通过 manifest.json 声明权限、资源限制、Hook、后台菜单与生命周期 SQL。

{
  "code": "demo-plugin",
  "version": "1.0.0",
  "permissions": ["content.read"],
  "hooks": [
    {
      "hook": "page.render",
      "type": "filter",
      "action": "payload_patch",
      "priority": 50,
      "fail_strategy": "fail_open"
    }
  ]
}

插件执行默认经过沙箱限制（超时、payload 大小、panic 恢复），并支持失败策略（fail_open/fail_close）和观测告警。

主题开发

前台主题位于 web/themes，采用 Go Template。推荐复用现有卡片、表单、状态标签样式，不新增与系统风格冲突的视觉语言。

• 主题切换与版本回滚可在后台主题管理页完成。
• 页面模板可结合 HTMX/Alpine.js 做轻交互增强。
• 涉及模板行为改动，需同步文档与进度记录。

可观测与运维

• 健康检查：/livez、/readyz、/healthz。
• 指标导出：/metrics（Prometheus 文本格式）。
• 发布约束：生产必须使用固定二进制或固定脚本启动，不使用 go run 常驻。
• 大变更后必须重编译并重启服务，避免“模板/路由已改但进程仍旧版本”。

参考文档索引