架构概述

概述

Kira CMS (Kira OP) 是 Kira 的运营后台系统，基于 Payload CMS 构建，用于管理用户数据和执行运营操作。

技术栈

类别	技术	说明
CMS 框架	Payload CMS 3.79.1	Headless CMS
运行时	Bun	JavaScript 运行时
前端框架	Next.js 16.2.0	启用 `experimental.serverActions: { bodySizeLimit: '10mb' }`
数据库	PostgreSQL	通过 Neon 托管
存储	S3 (Supabase Storage)	媒体文件
邮件	Resend	邮件发送
缓存	Redis KV (ioredis 5.10.1) → kira-dragonfly	Write-through + Read-through
部署	Fly.io (sjc)	容器化

项目结构

kira-cms

src

payload.config.ts

payload-types.ts

app

(payload)

admin

api

cached

home-cards

route.ts

announcements

route.ts

translate

route.ts

lark-notify

route.ts

layout.tsx

(frontend)

collections

Users.ts

Media.ts

DeletionLogs.ts

operation

Announcements.ts

HomeCardsV2.ts

Trending.ts

lib

lark.ts

components

NavLinks.tsx

Logo.tsx

Icon.tsx

HomeCardTabs.tsx

TranslateButton.tsx

views

DeleteAccount.tsx

DeleteAccountForm.tsx

目录	说明
`payload.config.ts`	Payload CMS 主配置
`collections/`	数据集合定义 (Collections)
`operation/`	运营数据定义 (Globals — 全局单例，区别于 Collections 的多记录集合)
`lib/`	工具库 (`lark.ts` — Lark webhook 通知)
`components/`	自定义 Admin UI 组件
`components/views/`	自定义视图页面
`app/(payload)/`	Payload Admin 路由
`app/(frontend)/`	前端公开页面

数据集合（Collections）

只有 3 个 Collection（多条记录的集合）：

Users

管理员用户账户。本地密码登录已禁用，身份完全由 Cloudflare Access 接管，Payload 只负责在首次访问时按 CF Access JWT 里的 email 创建/查找用户。

{
  slug: 'users',
  auth: {
    disableLocalStrategy: { enableFields: true, optionalPassword: true },
    strategies: [cloudflareAccessStrategy],
  },
  fields: []
}

cloudflareAccessStrategy（src/lib/cloudflareAccessStrategy.ts）验证 Cf-Access-Jwt-Assertion 请求头（JWKS + issuer + audience），按 email upsert 用户并返回给 Payload，实现零点击登录。

Media

媒体文件管理，存储到 S3。

DeletionLogs

用户删除操作日志记录。

{
  slug: 'deletion-logs',
  fields: [
    { name: 'userId', type: 'text' },
    { name: 'email', type: 'text' },
    { name: 'nickname', type: 'text' },
    { name: 'plan', type: 'text' },
    { name: 'credit', type: 'number' },
    { name: 'deletedAt', type: 'date' },
    { name: 'deletedBy', type: 'relationship', relationTo: 'users' }
  ]
}

Globals（全局单例）

3 个 Global：

Global	文件	用途
HomeCardsV2	`src/operation/HomeCardsV2.ts`	首页卡片（Featured/Image/Video/Audio 四分类）
Announcements	`src/operation/Announcements.ts`	首页公告横幅
Trending	`src/operation/Trending.ts`	首页 Trending 区（2026-03 新增）

Home Cards V1 已完全删除（e73bac9）。原 HomeCards.ts 已不存在，所有相关路由改到 V2。

自定义 Admin UI

HomeCardTabs（Category Tabs）

位置：src/components/HomeCardTabs.tsx:15

4 个标签：Featured / Image / Video / Audio
按 mediaType 和 isFeatured 过滤展示
Featured 标签隐藏 Add Card 按钮（源：HomeCardTabs.tsx:73-78，commit 71df4f2）
每个标签显示卡片计数

TranslateButton

位置：src/components/TranslateButton.tsx:26

支持 11 种非英文 locale
调用 /api/translate（内部 route，使用 OpenAI）
自动填充 {field}_{locale} 字段模式
导出两个变体：HomeCardTranslateButton、TrendingTranslateButton

架构图

功能模块

运营功能 (Operation)

功能	说明
Home Cards V2	首页功能卡片（Featured/Image/Video/Audio 四分类）
Announcements	首页公告横幅
Trending	首页 Trending 区（2026-03 新增）
Delete Account	用户账户删除

通用能力

自动翻译：所有多语言内容支持一键从英文翻译为 11 种语言（中文简繁体、日韩德法西意俄葡马来语） Arcade 教程引导：Home Cards 支持配置 Arcade 教程链接，用户可通过 ?guide={cardId} 访问交互式教程

部署

运行在 Fly.io（sjc + fra），零公网暴露：

fly.toml 无 [http_service] —— Fly 不开 443/80 公网端口
Dockerfile 多阶段 COPY cloudflared 二进制
start.sh 并行启动 node server.js 和 cloudflared tunnel
HOSTNAME="::" 让 Next.js 监听 IPv6 dual-stack（6PN 需要）

访问路径

来源	路径
外部浏览器	`op.kira.art` → CF edge → CF Access 鉴权 → Cloudflare Tunnel → container:4000
内部服务（kira-be）	`http://kira-cms.internal:4000` via Fly 6PN（绕过 Access，不受保护）

环境变量

DATABASE_URL                # PostgreSQL 连接
PAYLOAD_SECRET              # Payload 密钥
S3_*                        # S3 存储配置 (Supabase Storage)
RESEND_API_KEY              # 邮件服务
RESEND_FROM_EMAIL           # 邮件发送地址
NEXT_PUBLIC_API_URL         # Kira Backend URL (https://api.kira.art)
REDIS_URL                   # Redis KV 缓存 (kira-dragonfly)
OPENAI_API_KEY              # 翻译 API (gpt-5.2)
CLOUDFLARED_TOKEN           # CF Tunnel token（Zero Trust → Networks → Tunnels）
CF_ACCESS_TEAM_DOMAIN       # kiraart.cloudflareaccess.com
CF_ACCESS_APP_AUD           # Access app audience tag（Zero Trust → Access → Applications → kira-cms → Overview）

参考

同样模式的还有 kira-inngest，都是”Tunnel + CF Access + 6PN 内网”的零公网暴露部署。

Redis KV 缓存

使用 @payloadcms/kv-redis 实现 Redis KV 缓存，连接 kira-dragonfly 实例。

缓存策略

策略	说明
Write-through	数据变更时通过 Payload `afterChange` hooks 自动写入 Redis 缓存
Read-through	`/api/cached/*` 路由优先从 Redis 读取，缓存未命中时查询数据库并回填缓存

缓存路由

路由	Redis key	说明
`/api/cached/home-cards-v2`	`global_home-cards-v2`	HomeCardsV2 数据
`/api/cached/announcements`	`global_announcements`	公告数据
`/api/cached/trending`	`global_trending`	Trending 区

每个路由在响应中返回 X-Cache: HIT|MISS。命中时直接返回缓存；未命中时查 DB + 回填。

完整缓存链路

Admin Save → afterChange hook → Redis KV → /api/cached/* → kira-be /op/* → kira-web server fetch (60s ISR) → 用户端

Overview

Operations

概述

技术栈

项目结构

数据集合（Collections）

Users

Media

DeletionLogs

Globals（全局单例）

自定义 Admin UI

HomeCardTabs（Category Tabs）

TranslateButton

架构图

功能模块

运营功能 (Operation)

通用能力

部署

访问路径

环境变量

参考

Redis KV 缓存

缓存策略

缓存路由

完整缓存链路

工作流程

相关文档

Overview

Operations

Documentation Index

​概述

​技术栈

​项目结构

​数据集合（Collections）

​Users

​Media

​DeletionLogs

​Globals（全局单例）

​自定义 Admin UI

​HomeCardTabs（Category Tabs）

​TranslateButton

​架构图

​功能模块

​运营功能 (Operation)

​通用能力

​部署

​访问路径

​环境变量

​参考

​Redis KV 缓存

​缓存策略

​缓存路由

​完整缓存链路

​工作流程

​相关文档

概述

技术栈

项目结构

数据集合（Collections）

Users

Media

DeletionLogs

Globals（全局单例）

自定义 Admin UI

HomeCardTabs（Category Tabs）

TranslateButton

架构图

功能模块

运营功能 (Operation)

通用能力

部署

访问路径

环境变量

参考

Redis KV 缓存

缓存策略

缓存路由

完整缓存链路

工作流程

相关文档