Check CX Admin

check-cx-admin 是 check-cx 的后台管理项目——面板上每一个模型卡片，背后都是这里的一条配置。维护模型、Provider、请求模板、分组、允许登录的用户与系统通知：

• check_models：模型配置
• check_configs：Provider 配置
• check_request_templates：请求模板
• group_info：分组信息
• admin_users：后台 GitHub 允许用户目录
• system_notifications：系统通知
• check_history：检测历史（只读）
• check_poller_leases：轮询主节点状态（只读）

相关项目

• 前台监控面板：BingZi-233/check-cx：负责轮询检测、状态展示与只读 API；本项目负责后台管理。

推荐部署：check-cx 一键栈

本项目已并入 check-cx 的一键部署栈（完整 self-hosted Supabase + 面板 + 本后台）。用一键栈时不需要单独部署本项目，只需在 check-cx 仓库的 .env 中开启 GitHub OAuth：

GITHUB_ENABLED=true
GITHUB_CLIENT_ID=...
GITHUB_SECRET=...
ADMIN_EMAILS=your@email.com
APP_URL=http://localhost:3001

详见 check-cx README。单独部署（对接云 Supabase 或已有实例）继续往下看。

主要技术栈：Next.js 16 App Router、React 19、shadcn/ui、Supabase Auth + Supabase Database。

本地开发

pnpm install
cp .env.example .env.dev   # 注意：pnpm dev 读取的是 .env.dev
pnpm dev

默认访问地址为 http://localhost:3000。

环境变量

环境变量示例请参见 .env.example。

必填

• SUPABASE_URL
• SUPABASE_PUBLISHABLE_OR_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY

可选

• SUPABASE_DB_SCHEMA：后台数据库 schema，默认 public；单库调试时可设为 dev
• APP_URL：后台对外访问地址；在反向代理或 Docker 生产环境中，建议显式设置，例如 https://admin.example.com
• SUPABASE_OAUTH_PROVIDERS：默认 github；当前后台只接受 GitHub OAuth
• ADMIN_EMAILS：逗号分隔的 bootstrap 管理员 GitHub 邮箱；仅用于首个管理员兜底，不配置时不会自动放行任何人

认证说明

• 登录页只接受 GitHub OAuth。
• 登录、OAuth 发起、回调及登出流程均由服务端处理。
• /dashboard/** 路由受 Supabase 会话保护。
• 后台默认是允许名单制：普通用户必须先把 GitHub 登录邮箱写入 admin_users，并预设其 group_name。
• 管理员可以通过 /dashboard/users 维护允许名单；对方首次使用 GitHub 登录后会自动绑定 auth_user_id。
• 如果命中 ADMIN_EMAILS，且该 GitHub 邮箱被用来登录，该账号会被当作 bootstrap 管理员处理；这只是兜底方案，不建议代替允许名单长期使用。
• 普通成员登录后只能查看和维护自己 group_name 下的配置；管理员可以查看全部配置。
• 后台所有数据库读写都走 SUPABASE_DB_SCHEMA 指定的 schema；未设置时默认使用 public。
• 项目认证配置在服务端运行时读取，便于在 Docker 等部署环境中通过环境变量覆盖。
• 生产环境建议显式设置 APP_URL；否则 OAuth 回调地址会依赖请求头，在反向代理配置不当时可能错误地指向 http://localhost:3000。
• 同时需要在 Supabase Auth 的 Redirect URLs 中加入 APP_URL/auth/callback，例如 https://admin.example.com/auth/callback。云 Supabase 在 Auth 设置页配置；self-hosted 一键栈对应 .env 中的 SITE_URL / ADDITIONAL_REDIRECT_URLS。

Docker

本地构建镜像

docker build -t check-cx-admin:local .

本地运行容器

请先准备 .env 文件，变量名与 .env.example 保持一致。

docker compose up -d

镜像在运行时直接读取 SUPABASE_URL、SUPABASE_PUBLISHABLE_OR_ANON_KEY、SUPABASE_SERVICE_ROLE_KEY、APP_URL、SUPABASE_OAUTH_PROVIDERS、ADMIN_EMAILS，不会将这些值固化到前端构建产物中。

镜像 tag 说明：CI 只在 v* tag 上发布 docker.io/bingzi233/check-cx-admin:<version>（不带 v 前缀）和 :latest。

生产部署示例

生产环境不建议直接使用 latest 标签，推荐固定使用明确的版本 tag。

1. 准备目录

mkdir -p /opt/check-cx-admin
cd /opt/check-cx-admin

2. 写入环境变量

创建 .env 文件：

SUPABASE_URL=https://service.check-cx.org
SUPABASE_PUBLISHABLE_OR_ANON_KEY=你的_anon_key
SUPABASE_SERVICE_ROLE_KEY=你的_service_role_key
SUPABASE_DB_SCHEMA=public
APP_URL=https://admin.example.com
SUPABASE_OAUTH_PROVIDERS=github
ADMIN_EMAILS=admin@example.com

3. 配置 Supabase Auth 回调白名单

至少加入以下回调地址：

https://admin.example.com/auth/callback

如果本地开发环境也需要测试 OAuth，可额外加入：

http://localhost:3000/auth/callback

单库 dev 调试

如果正式和调试共用同一个 Supabase 项目，可以把后台切到 dev schema：

SUPABASE_DB_SCHEMA=dev

前提是上游数据库已经存在 dev.check_configs、dev.group_info、dev.admin_users 等对象。当前后台头部会显示 schema: dev 或 schema: public，避免你调错空间。

4. 写入生产 compose

创建 docker-compose.yml 文件（image 使用明确版本 tag，例如 0.3.3）：

services:
  check-cx-admin:
    image: bingzi233/check-cx-admin:0.3.3
    container_name: check-cx-admin
    restart: unless-stopped
    ports:
      - "3000:3000"
    env_file:
      - .env
    environment:
      NODE_ENV: production
      APP_URL: ${APP_URL}

如果前置使用 Nginx、Caddy 或 Traefik 等反向代理，建议仅将容器绑定到内网端口。此处为便于演示，直接暴露 3000 端口。

5. 启动

docker compose pull
docker compose up -d

6. 更新版本

将 image 从旧版本 tag 更新为新版本 tag 后，执行：

docker compose pull
docker compose up -d

7. 查看日志

docker compose logs -f check-cx-admin

GitHub Actions

仓库当前包含以下两条工作流：

• .github/workflows/ci.yml：在 main push 和 PR 上执行 pnpm lint、pnpm build
• .github/workflows/docker.yml：推送 v* tag 或手动触发时，发布 docker.io/bingzi233/check-cx-admin

Docker 发布工作流需要配置以下 Secrets：

• DOCKERHUB_USERNAME
• DOCKERHUB_TOKEN

发版方式

推送版本 tag

git tag v0.3.3
git push origin v0.3.3

推送后，docker.yml 会自动构建并发布以下镜像（版本 tag 不带 v 前缀）：

• docker.io/bingzi233/check-cx-admin:0.3.3
• docker.io/bingzi233/check-cx-admin:latest

手动触发

也可以在 GitHub Actions 页面手动触发 Build and Push Docker Image 工作流。

当前页面

• /login：登录页
• /dashboard：概览
• /dashboard/models：模型配置
• /dashboard/configs：Provider 配置
• /dashboard/templates：请求模板
• /dashboard/groups：分组信息
• /dashboard/notifications：系统通知
• /dashboard/history：检测历史
• /dashboard/system：运行状态
• /dashboard/users：GitHub 允许用户目录

数据权限建议

该后台默认通过 SUPABASE_SERVICE_ROLE_KEY 读写管理表。原因在于上游项目当前的 RLS 策略主要面向前台读取场景，尚未为管理后台提供完整的写入策略。

请勿将 SUPABASE_SERVICE_ROLE_KEY 暴露到客户端。当前项目已将其限制为仅在服务端使用。