跳转到内容
cikioCIKIO 文档

CCU 开发

ccu/ 是 CCU-MC 社区主站：资产库、工程工坊、站内文档、问卷、公告。 身份不在本站 —— 注册登录由 authserver 承担，讨论与帖子归 forum。

项 值
包名 cikio-ccu
线上地址 https://ccu.cikio.cn
技术栈 Astro 7（output: 'server'）+ @astrojs/cloudflare 14 + Tailwind 4 + daisyUI 5
存储 D1 ccu-db、R2 ccu-assets
客户端 零框架：原生 fetch + 表单渐进增强

一、目录与分层

Section titled “一、目录与分层”
ccu/
├─ src/pages/          # 路由（.astro 页面 + api/*.ts 接口 + [numId] 动态路由）
├─ src/components/     # 布局、导航与 ui/ 基础组件；asset/、project/、admin/ 为业务组件
├─ src/db/             # schema.ts（单文件，全部表）+ index.ts（Drizzle D1 客户端）
├─ src/lib/            # 业务逻辑；queries/ 只读查询、write/ 写入入口
├─ src/interfaces/     # 内部数据接口类型
├─ src/styles/global.css
├─ src/env.d.ts        # Cloudflare.Env 与 App.Locals 类型声明
├─ src/config.ts       # 站点级常量
├─ src/middleware.ts   # 只对受保护路径校验会话
├─ drizzle/            # 迁移 SQL + meta/
├─ public/             # favicon 等静态资源
└─ docs/               # 仓库内部设计文档（data-model / asset-fields / api-contract）

三条铁律（违反会被 review 打回）：

  1. pages/*.astro 只做「取数 → 组装组件 → 渲染」，不写 SQL、不写业务判断。
  2. 一切写入收进 src/lib/ 下的单写入口：必须支持幂等键、可解释错误、不静默降级。
  3. 绑定统一从 @lib/env 取：不要 import ... from 'cloudflare:workers'，也不要 const env = … —— 前者在 .astro 里类型报错，后者会绕过统一的读取入口。

公开页面不检查会话（middleware.ts 只护受保护路径），登录按需触发，不做全站登录墙。

二、路由与接口

Section titled “二、路由与接口”
  • 页面走文件路由：/、/about、/community、/project、/docs、/polls、/account、/admin/* 等； 详情页是 /project/[numId]、/asset/[numId]。
  • 写入接口在 src/pages/api/ 下（资产、工程、认证回调、登出、审核动作、后台操作等）； 另有 src/pages/auth/backchannel-logout.ts（接收 authserver 的登出广播）与 src/pages/storage/[...key].ts（对象存储读取）。
  • 对外一律用 num_id（可读的用户可见编号），数据库自增主键不暴露在 URL 上。
  • 不使用 Astro Actions：表单与写入统一走 api/ 路由 + lib/ 单写入口。

三、运行时绑定与配置

Section titled “三、运行时绑定与配置”
项 说明
DB D1 ccu-db，migrations_dir = "drizzle"
BUCKET R2 ccu-assets（资产与工程图片）
ASSETS 构建产物 ./dist
[vars] AUTHSERVER_URL、CCU_OIDC_CLIENT_ID

CCU_OIDC_CLIENT_ID 可以公开：本站是公开客户端（PKCE 强制、无 client_secret）， wrangler.toml 与 secrets 里都没有客户端密钥。机密一律走 wrangler secret put。

四、本地开发

Section titled “四、本地开发”
终端窗口
pnpm --filter cikio-ccu run dev         # astro dev
pnpm --filter cikio-ccu run typecheck   # astro check
pnpm --filter cikio-ccu run build       # astro build
pnpm --filter cikio-ccu run db:migrate:local

本地 astro dev 的运行时绑定由 Cloudflare 工具链在本地模拟，不需要远程 D1 / R2； 本地库的结构用 db:migrate:local 建立。需要看真实数据时再自行连远程库。

五、数据与迁移

Section titled “五、数据与迁移”

  • schema 是单文件 src/db/schema.ts（全部表）。

  • 配置：drizzle.config.ts（sqlite、schema 指向上面那个文件、输出 drizzle/）。

  • 流程：

    终端窗口
    pnpm --filter cikio-ccu run db:generate   # schema → drizzle/*.sql
    pnpm --filter cikio-ccu run db:migrate:local
    pnpm --filter cikio-ccu run db:migrate    # --remote，必须早于部署

  • 禁用数据库触发器：CREATE TRIGGER 的 SQL 体含分号，wrangler d1 migrations apply 会把它拆成多条语句， 触发器实际从未生效。需要自增/默认值就在写入前显式算好再传进 INSERT。

  • 表结构别凭记忆：Drizzle 不做运行时列校验，写错列只在运行到那一行时崩；改查询前先看 schema.ts。

  • 站点的技术设计与字段矩阵在 ccu/DESIGN.md、ccu/docs/（内部文档，不对外发布）。

六、构建与部署

Section titled “六、构建与部署”
终端窗口
pnpm --filter cikio-ccu run build     # 产物 dist/client（静态）+ dist/server（Worker 入口 entry.mjs）
pnpm --filter cikio-ccu run deploy    # astro build && wrangler deploy

CI 的 build job 会校验 ccu/dist/client、ccu/dist/server 与 dist/server/entry.mjs 三个产物都存在。 上线用本地 wrangler CLI（Cloudflare 侧没接 GitHub 自动构建），自定义域 ccu.cikio.cn 已在 wrangler.toml 里以 routes + custom_domain 声明。

七、样式

Section titled “七、样式”

Tailwind 4（Vite 插件）+ daisyUI 5，主题为 winter / dracula，支持三级主题切换（浅色 / 深色 / 跟随系统）。 改主题变量时保持与既有变量桥接方式一致，不要在页面里硬编码颜色值。

相关：CCU（产品视角）、认证服务开发、开发问题与踩坑记录。