功能配置

站点功能的统一配置入口是 config/community-template.json。优先通过配置启用或关闭模块，不要把删除页面、注释 API 注册当作日常开关方式。

配置结构

json

{
  "schemaVersion": 2,
  "identity": {
    "name": "我的社区",
    "shortName": "社区",
    "locale": "zh-CN"
  },
  "modules": {
    "community": true,
    "content": true,
    "subscriptions": true,
    "commerce": false,
    "events": false,
    "ama": false,
    "makerDirectory": false,
    "makerNeeds": false,
    "githubDiscovery": false,
    "automation": false,
    "assistant": false,
    "notifications": true,
    "messageAutomation": true,
    "invitations": true,
    "referrals": true,
    "softwareDelivery": false
  },
  "providers": {
    "storage": "qiniu",
    "payment": "alipay_wechat",
    "email": "smtp",
    "video": "tencent_vod",
    "ai": "minimax"
  }
}

修改后先验证：

bash

pnpm --filter @zaowu/template-core validate:config -- config/community-template.json

验证器会输出站点身份、已启用模块和 Provider 名称，不会读取或输出 .env 中的密钥。

模块矩阵

键	能力	主要依赖
`community`	动态、帖子、闪念与互动	基础身份服务
`content`	文章、集合、内容附件与购买基础	基础身份服务
`subscriptions`	订阅、会员与积分	支付配置
`commerce`	小铺、订单与履约	`content`
`events`	活动、报名、票务、签到、票种折扣码与兑换码	支付配置；定时维护用于释放过期支付预留
`ama`	公开问答与咨询预约	`subscriptions`
`makerDirectory`	Maker 目录、推荐与资料纠错	无强制模块依赖
`makerNeeds`	需求墙与联系授权	基础身份服务
`githubDiscovery`	GitHub 公开仓库发现示例	GitHub 官方 API，可选 Token
`automation`	通用健康巡检、摘要预览与任务运行记录	独立 Worker；通用示例默认 dry-run
`assistant`	AI 助手	AI Provider
`notifications`	站内通知	`community`
`invitations`	邀请码与邀请关系	基础身份服务
`referrals`	跨会员、内容、实物、数字商品、活动与积分补充的推荐返利	`subscriptions`；支付配置
`softwareDelivery`	私有源码版本和下载权益	`subscriptions`、私有交付存储

配置 schema 当前会拒绝以下不一致组合：

启用 ama 却关闭 subscriptions。
启用 commerce 却关闭 content。
启用 notifications 却关闭 community。
启用 referrals 却关闭 subscriptions。
启用 softwareDelivery 却关闭 subscriptions。

开关实际控制什么

模块开关已经控制：

Space Web 主导航和移动端导航。
对应 Web 路由返回 404，而不是只隐藏入口。
Space API 对应路由返回统一的 MODULE_DISABLED 404。
/v1/app 暴露非敏感的站点身份、模块状态和 Provider 名称，供客户端决定入口。

当前需要手动处理：

更细粒度的后台扩展流程需要部署者在自己的模块中继续声明权限。
自定义 Worker 任务需要自行声明读写范围、重试和审计策略。
sitemap、搜索索引和通知类型的统一生成。

源码包含这些通用模块所需的迁移。关闭模块不会自动删除已有表或数据，因此重新启用不会丢失历史内容。

自行开发新模块时，需要同时声明导航、页面、API、权限、数据迁移、任务和测试，并在包含内容与使用边界中补充它的外部依赖与生产责任。

从上游同步页面或组件后，还要执行视觉走查：商业与活动页面正文和辅助文字不得低于 12px；图片必须核对实际渲染尺寸、裁切和缺图兜底；桌面与 390px 移动视口都不能出现横向溢出。不能仅以资源请求成功或页面可打开作为通过标准。

配置和机密的边界

community-template.json 可以提交：站点名称、模块开关、Provider 标识。

.env 不得提交：数据库密码、Cookie secret、OAuth secret、支付私钥、对象存储 Secret、下载签名 Secret、推荐归因签名 Secret、加密密钥。启用推荐返利时，为 SPACE_REFERRAL_TOKEN_SECRET 配置独立的 32 位以上高熵值；不要与邀请、活动或小铺旧归因密钥复用。生产部署前的安全预检会拒绝示例值、短密钥、非 HTTPS 公网地址和 Mock 支付。

七牛作为生产存储 Provider 时，头像、帖子图片、通用附件、工具库图片和最前线发布截图的 *_PUBLIC_BASE_URL 必须在生产 .env 中显式填写真实 HTTPS CDN origin。仓库中的 assets.example.com 仅是交付模板占位值；预检会拒绝缺失、示例域名、带路径、HTTP、localhost、私网或保留地址，避免上传成功后把不可访问的示例 URL 写入业务数据。

活动、小铺或数字商品启用后，保持 COMMUNITY_COMMERCE_MAINTENANCE_ENABLED=true。独立 Worker 会使用 SPACE_MACHINE_TOKEN 调用站内维护接口，关闭超时待支付记录并释放库存、活动名额和仍处于预占状态的代码。这个交易维护开关独立于 COMMUNITY_AUTOMATION_DRY_RUN；后者只控制健康巡检、摘要预览等通用自动化示例。

功能配置 ​

配置结构 ​

模块矩阵 ​

开关实际控制什么 ​

配置和机密的边界 ​

功能配置

配置结构

模块矩阵

开关实际控制什么

配置和机密的边界