Awd

.github/workflows/ci.yml

@@ -2,32 +2,67 @@ name: CI
 
 on:
   push:
-    branches: [master, main]
+    branches: [awd, main, master]
   pull_request:
-    branches: [master, main]
+    branches: [awd, main, master]
+  workflow_dispatch:
 
 permissions:
   contents: read
 
 env:
   CARGO_TERM_COLOR: always
 
+# 三层分层（CI-fast / CI-docker / CI-host-network，见下）：
+#   CI-fast（PR 必跑）        —— 单测 + mock + 架构/安全 grep
+#   CI-docker（PR 或 on-demand）—— Docker E2E（Flag/Judge smoke + 场景 A/B/C/G/H）
+#   CI-host-network（手动触发）—— root + nftables/WG 系统级场景 D/E/F/I
 jobs:
-  rust:
-    name: Rust checks
+  fast-rust:
+    name: CI-fast · Rust unit + security grep
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: rustfmt, clippy
       - uses: Swatinem/rust-cache@v2
-      - run: cargo fmt --all
+      # 注意：`cargo fmt --all` 是「写入模式」，即使有格式违规也退出 0（只是静默改写文件），
+      # 因此它不是门禁；必须用 `-- --check` 才会在违规时非零退出。
+      - run: cargo fmt --all -- --check
       - run: cargo clippy --workspace --all-targets --all-features
-      - run: cargo test --workspace
+      - run: cargo test --workspace --lib
+      # 集成测试（apps/api/tests/ 下 44 个独立 crate target）不在 `--lib` 范围内，它们只在
+      # CI-docker 任务里真正执行。这里强制它们至少**编译通过**：PR 全绿不该掩盖「共享
+      # helper / 契约目录改坏导致集成测试编译失败」这类问题。
+      - run: cargo test --workspace --tests --no-run
+      - name: Security architecture grep (P5-12)
+        run: |
+          # 两个坑，都曾让守卫失真：
+          #  1) grep 对不存在的路径返回 2，直接放进 `if` 会「静默放行」→ 先断言路径存在；
+          #  2) 注释里「提到」禁止项也会命中 → 只检查非注释行，并限定 *.rs
+          #     （apps/api/src/sql/ 下是冻结的 migrations，不该被这些守卫约束）。
+          for p in apps/api/src/bootstrap apps/api/src apps/api/src/modules/event/awd apps/api/src/modules/event/awdp; do
+            [ -d "$p" ] || { echo "FAIL: $p missing (path drifted; guard would silently pass)"; exit 1; }
+          done
+          # 过滤掉 Rust 注释行：`//`、`/*`、块注释续行 `* `、结束行 `*/`。
+          # 注意用 `\*[[:space:]]` 而非裸 `\*`，否则会误滤以解引用开头的真实代码行（`*ptr = ..`）。
+          code_only() { grep -vE ':[0-9]+:[[:space:]]*(//|/\*|\*[[:space:]]|\*/)'; }
+          if grep -rn --include='*.rs' 'vec!\[0u8; 32\]' apps/api/src/bootstrap | code_only; then
+            echo "FAIL: zero-key fallback"; exit 1
+          fi
+          if grep -rn --include='*.rs' 'nft flush ruleset' apps/api/src | code_only; then
+            echo "FAIL: nft flush ruleset forbidden"; exit 1
+          fi
+          for d in apps/api/src/modules/event/awd apps/api/src/modules/event/awdp; do
+            if grep -rn --include='*.rs' 'sh -c' "$d" | code_only; then
+              echo "FAIL: shell concat forbidden in $d"; exit 1
+            fi
+          done
+          echo "security greps OK"
 
-  web:
-    name: Web checks
+  fast-web:
+    name: CI-fast · Web checks
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -44,3 +79,46 @@ jobs:
       - run: pnpm --filter @floatctf/web lint
       - run: pnpm --filter @floatctf/web test
       - run: pnpm --filter @floatctf/web build
+
+  docker-e2e:
+    name: CI-docker · AWD infra smoke (on-demand)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, 'docker-e2e')
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: floatctf_db
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # 这里才是集成测试（apps/api/tests/）真正执行的作业：无 live API 时它们自行 soft-skip，
+      # 需要行为级验证时在 PR 上打 `docker-e2e` 标签或手动 dispatch。
+      - run: cargo test --workspace
+      - name: Flag/Judge smoke（真构建 bookworm 二进制 + 起容器 + /health）
+        run: ./apps/api/scripts/e2e_flag_judge.sh
+        env:
+          RUN_DOCKER_TESTS: "1"
+
+  host-network:
+    name: CI-host-network · nftables/WG scenarios (nightly)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: nftables prototype gate (P1-0, needs CAP_NET_ADMIN)
+        run: sudo -E apps/api/scripts/nft_prototype.sh
+      - name: cargo unit (host)
+        run: cargo test --workspace

.github/workflows/release.yml

@@ -9,11 +9,14 @@ permissions:
   contents: write
 
 jobs:
-  web:
-    name: Build web release
-    runs-on: ubuntu-latest
+  release:
+    name: Build release artifacts
+    # API runtime image 固定 ubuntu:24.04；构建机同版可避免 release ELF 引用更新 glibc。
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
+
+      # ── 前端 ──
       - uses: pnpm/action-setup@v4
         with:
           version: 11.20.0
@@ -25,22 +28,66 @@ jobs:
           cache-dependency-path: pnpm-lock.yaml
       - run: pnpm install --frozen-lockfile
       - run: pnpm --filter @floatctf/web build
-      - run: tar -czf web-dist.tar.gz -C apps/web/dist .
-      - uses: softprops/action-gh-release@v2
-        with:
-          files: web-dist.tar.gz
-          generate_release_notes: true
 
-  rust:
-    name: Build Rust release
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
+      # ── 后端（全 workspace 二进制）──
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
-      - run: cargo build --workspace --release
-      - run: tar -czf rust-binaries.tar.gz -C target/release floatctf fcmc floatctf-migration awd_flagserver awd_judgeserver
-      - uses: softprops/action-gh-release@v2
+      # Release 只构建真正发布的 API + host helper 二进制。
+      # 不构建 tests / benches / examples，也不为未发布的 workspace bin 产生本地 artifact。
+      - run: cargo build --locked --release -p floatctf -p floatctf-helper --bins
+
+      # ── 发布 4 个产物（供 install.sh 下载部署）──
+      #   1. floatctf            API 二进制（installer 以此本地构建生产容器 image）
+      #   2. floatctf-helper   宿主控制面二进制
+      #   3. web-dist.tar.gz     前端静态产物
+      #   4. merged.sql          单个 SQL（fresh-DB bootstrap）
+      - name: Assemble release artifacts
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          # 1) API 二进制
+          install -m 0755 target/release/floatctf floatctf
+
+          # 2) 宿主控制面
+          install -m 0755 target/release/floatctf-helper floatctf-helper
+
+          # 3) 前端静态产物
+          tar -czf web-dist.tar.gz -C apps/web/dist .
+
+          # 4) merged.sql（确定性 fresh-DB bootstrap）
+          bash apps/api/src/sql/migrate.sh make
+          install -m 0644 apps/api/src/sql/merged.sql merged.sql
+
+          echo "release artifacts:"
+          ls -la floatctf floatctf-helper web-dist.tar.gz merged.sql
+
+      - name: Verify production API image
+        shell: bash
+        run: |
+          set -euo pipefail
+          rm -rf .release-api-image
+          mkdir .release-api-image
+          install -m 0755 floatctf .release-api-image/floatctf
+          version="${GITHUB_REF_NAME#v}"
+          docker build \
+            --build-arg "FLOATCTF_VERSION=${version:-ci}" \
+            -f infra/docker/api/Dockerfile \
+            -t floatctf/api:release-test \
+            .release-api-image
+          test "$(docker image inspect -f '{{.Config.User}}' floatctf/api:release-test)" = "65532:65532"
+          docker run --rm --entrypoint sh floatctf/api:release-test -c '
+            set -eu
+            ldd /usr/local/bin/floatctf | tee /tmp/ldd.txt
+            ! grep -q "not found" /tmp/ldd.txt
+          '
+
+      - name: Upload release artifacts
+        uses: softprops/action-gh-release@v2
         with:
-          files: rust-binaries.tar.gz
+          files: |
+            floatctf
+            floatctf-helper
+            web-dist.tar.gz
+            merged.sql
           generate_release_notes: true

.gitignore

@@ -8,7 +8,13 @@ dist/
 /app
 /tmp
 /chore
+/.mnemon
+/HANDOFF.md
 /var
 /.codegraph/
 # migrate.sh 的 flock 锁文件（临时）
 apps/api/src/sql/.migrate.lock
+apps/api/src/sql/merged.sql
+/examples/*.zip
+__pycache__/
+release/

AGENTS.md

@@ -6,41 +6,59 @@
 
 基于 Rust（Actix Web + SeaORM + PostgreSQL + RustFS）与 React 的 CTF 实训/竞赛平台（Jeopardy + AWD 双赛制），monorepo 结构：`apps/api`（后端）、`apps/web`（前端）、`crates/`（共享与独立服务）。
 
+## HANDOFF.md（会话交接记忆）
+
+若项目根目录存在 `HANDOFF.md`，说明上一会话/开发者留下了交接记忆：**先完整读取并记住其中的内容（上下文、决策、未完成事项、约束），再开始任何任务**；工作过程中若有新增的关键决策/进展，也及时同步写回该文件，供下次会话延续。该文件是开发者私有的会话记忆，已被 gitignore，不会提交共享。
+
 ## 必读文档
 
 | 文档 | 用途 |
 |------|------|
 | [docs/agents/ARCHITECTURE.md](docs/agents/ARCHITECTURE.md) | 架构速览：模块分层、关键类型、配置体系、数据流 |
 | [docs/agents/ADD-FEATURE.md](docs/agents/ADD-FEATURE.md) | **开发新功能**：8 步流程 + 测试清单 |
 | [docs/agents/FIX-BUG.md](docs/agents/FIX-BUG.md) | **修 bug**：复现/定位/根因/最小修复/回归 |
-| [docs/agents/DATABASE.md](docs/agents/DATABASE.md) | **改数据库**：迁移 → 应用 → 实体/类型再生成 |
+| [docs/agents/DATABASE.md](docs/agents/DATABASE.md) | **改数据库**：迁移 → 应用 → 实体/类型再生成（**已有 migrations 不可直接改**） |
 | [docs/agents/DATA-FETCHING.md](docs/agents/DATA-FETCHING.md) | **前端数据页面**：缓存分级、keepPreviousData、queryKey 失效 |
 | [docs/agents/TESTING.md](docs/agents/TESTING.md) | 测试规范：层级、写法、禁忌 |
+| [docs/agents/RULES.md](docs/agents/RULES.md) | **用户反复强调的规则与返工教训**：前端形态细则、禁原生弹窗、数据必须真实、环境约定 |
 
 ## 铁律（违反即返工）
 
 1. **配置只从 TOML 读取**：`FLOATCTF_CONFIG` → `apps/api/config/development.toml` → `AppConfig`（经 `ReqCtx.config` 注入）。禁止新增环境变量读取；动态设置用 `get_setting`。
-2. **实体是生成的**：手改 `apps/api/src/entity/` 会被覆盖。Schema 变更必须：`mise run db:migration:new` → 写幂等 SQL + 中文 COMMENT → `db:migration:merge` → 应用到开发库 → `mise run db:gen`。**sea-orm-cli 必须 1.1.20**（2.0.1 生成产物会导致全项目编译失败）。
-3. **三处一致**：数据库 Schema / 生成实体 / 业务代码引用必须一致（`entity/代码/库` 漂移是历史最高频 bug 源）。
-4. **敏感值走 `Secret`**：Debug/日志必须脱敏；`auth.jwt_secret` 等不落日志、不入库。
-5. **提交规范**：中文 message（feat/fix/chore/docs/refactor 前缀），按角度分批提交；提交前 `cargo fmt --all && cargo check -p floatctf` 与相关测试全绿。**push 前必须本地完整过一遍验证**：`mise run check` 全绿，前端额外 `tsc --noEmit` 与 `vite build` 通过（CI 跑的是 `vite build && tsc`，本地不绿推送必红）。
-6. **先诊断后修复**：修 bug 先定位根因并给证据；涉及行为/数据变更，先向用户说明方案获批后再动手。
+2. **Migrations 只前进，无论如何都不可以直接动已有迁移文件**：`apps/api/src/sql/migrations/` 下**已经存在**的文件（含 baseline `20260810121925-initial-schema.sql` / `20260810121926-initial-data.sql`，以及任何已提交或已 apply 的迁移）**绝对禁止**直接修改、删除、重命名、重写、squash、回滚式改写。改 Schema / 修 Schema 错误 / 补数据 **只能** `mise run db:migration:new <名称>` 追加**新**迁移，把 SQL 写进这个新文件。禁止手改 `merged.sql`（生成产物）；禁止在 migration 或业务代码里操作 `schema_migrations`（由 migrate.sh 独占）。唯一允许写入的对象：刚 `new` 出来、尚未 apply、尚未作为历史固化的**新文件**。详细见 [DATABASE.md](docs/agents/DATABASE.md)。
+3. **实体是生成的**：手改 `apps/api/src/entity/` / `apps/web/src/entity/` 会被覆盖。Schema 变更流程：`db:migration:new` → 写幂等 SQL + 中文 COMMENT（**文件内禁止 BEGIN/COMMIT**）→ `db:migration:validate` → `db:migration:apply` → `mise run db:gen`。`merged.sql` 由 release 流程从 migrations 确定性生成；日常开发启动不依赖它。**sea-orm-cli 必须 1.1.20**。`public.schema_migrations` 不是领域实体（generator 已排除）。API 计算字段（如 settings `resolved_value`）放 manual DTO，不要写回生成文件。
+4. **三处一致**：数据库 Schema / 生成实体 / 业务代码引用必须一致（`entity/代码/库` 漂移是历史最高频 bug 源）。
+5. **敏感值走 `Secret`**：Debug/日志必须脱敏；`auth.jwt_secret` 等不落日志、不入库。
+6. **宿主权限只走 helper**：生产 API 是 Compose 内的非 root 容器，必须保持 `cap_drop=ALL`、`no-new-privileges`、read-only rootfs，禁止挂载 `/var/run/docker.sock`、加入 docker 组或获得 `CAP_NET_ADMIN`；Docker 走 `helper-docker.sock`，WireGuard/nftables/conntrack 走 `helper-control.sock`。新增高权限能力必须先扩展 helper 的受限协议/策略。宿主 systemd 只管理 `floatctf-helper.service` + `floatctf-infra.service`/`floatctf.target`，不要恢复 `floatctf-api.service`。
+7. **提交规范**：中文 message（feat/fix/chore/docs/refactor 前缀），按角度分批提交；提交前 `cargo fmt --all && cargo check -p floatctf` 与相关测试全绿。**push 前必须本地完整过一遍验证**：`mise run check` 全绿，前端额外 `tsc --noEmit` 与 `vite build` 通过（CI 跑的是 `vite build && tsc`，本地不绿推送必红）。
+8. **先诊断后修复**：修 bug 先定位根因并给证据；涉及行为/数据变更，先向用户说明方案获批后再动手。
+9. **前端仿照既有页面**：新页面先找同域参照页（赛事详情参照 `service/events/jeopardy.$id/*` 与 `awd.$id/*`、管理列表参照 `admin/challenges.tsx`、导航配置参照 `navigation/*`），结构/布局/交互与参照页保持一致；优先复用 `components/` 现有组件（GenericTable、EventStatusBadge、SubmitWriteup、MsgBanner、AppLink、FilterBar 等）与 `@primer/react`，禁止另起炉灶自创视觉风格或手写重复实现。管理页必须用 Challenges 内置 GenericTable 增删改查形态、样式对照要"一模一样"、默认最简方案等细则与全部返工案例见 [RULES.md](docs/agents/RULES.md)。
+10. **用户偏好（详细见 [RULES.md](docs/agents/RULES.md)）**：禁止原生 `alert(`/`confirm(` 弹窗（一律用 Primer `useConfirm`/`Dialog`/`useMsgBanner`）；展示数据必须来自真实接口、禁止假数据/占位糊弄（"不要随便搞点数据糊弄我"），状态判定必须与后端一致。
 
 ## 常用命令速查
 
 ```bash
-mise run infra:up / infra:logs / infra:down   # 基础设施（Postgres/RustFS/Nginx）
-mise run dev:api / dev:web / dev              # 启动开发服务
-mise run db:migration:new <名称>               # 新建 SQL 迁移
-mise run db:migration:merge                    # 合并迁移 → merged.sql
-mise run db:gen                                # 重新生成 Rust 实体 + TS 类型
-mise run fmt / lint / test / check / build     # 质量门禁
-cargo test -p floatctf <关键词>                 # 跑指定单元测试
+mise run setup                              # 新开发机一次性：工具链 + 主机能力 + helper
+mise run dev                                # 唯一开发入口：infra + migrations + API watch + Vite
+mise run dev:down / dev:reset / dev:logs    # 停止 / 清库重建 / 基础设施日志
+mise run db:migration:new <名称>             # 新建 SQL 迁移（文件内无 BEGIN/COMMIT）
+mise run db:migration:validate              # 校验迁移文件（不连库）
+mise run db:migration:status                # 查看迁移状态（只读）
+mise run db:migration:verify                # 校验迁移历史（checksum）
+mise run db:migration:apply                 # 执行未应用的迁移，fresh DB 可从 #1 开始
+mise run db:migration:merge                 # release/fresh-production 用 merged.sql
+mise run db:gen                             # 重新生成 Rust 实体 + TS 类型
+mise run fmt / lint / test / check / build   # 质量门禁
+cargo test -p floatctf <关键词>               # 跑指定单元测试
 ```
 
 ## 开发环境速记
 
-- API：`http://localhost:9090`（mise run dev:api）；Web：`http://localhost:3000`；统一入口 `http://localhost:7780`（Nginx）
-- 开发库：`postgres://postgres:postgres@127.0.0.1:5432/floatctf_db`（容器 floatctf-dev-db）
-- 对象存储：RustFS `http://127.0.0.1:9000`（桶 `floatctf-public` / `floatctf-private`）
-- 配置样例：`apps/api/config/development.toml`；启动日志：`WORK_DIR/logs/api/`（按天滚动，开发库 WORK_DIR=`../../app` → `app/logs/api/`）
+- 唯一开发模式：`mise run dev`；不存在 A/B 双轨与 `floatctf-dev-infra.service`。
+- API：当前开发者 UID 运行，`watchexec` 自动重编译/重启；`dev-api-run.sh` 每次启动时丢弃 docker 等附加组和 capabilities；Web：Vite HMR。
+- 宿主控制面：`floatctf-helper.service`，用户 `floatctf-helper` + docker group + `CAP_NET_ADMIN`；API 通过 `/run/floatctf/helper-control.sock` 与 `/run/floatctf/helper-docker.sock` 调用，API 自身无 Docker socket / 网络 capability。
+- 开发库：`postgres://postgres:postgres@127.0.0.1:5432/floatctf_db`；fresh DB 直接 `migration apply`，开发启动不需要 `merged.sql`。
+- Redis：`redis://127.0.0.1:6379`；RustFS：`http://127.0.0.1:9000`；Caddy/DB/Redis/RustFS 开发端口均回环绑定。Redis 是 API 必需基础设施：正常开发/生产必须提供 `[redis].url` 且 bootstrap PING 成功；禁止重新引入“未配置 Redis 也能正常启动”的生产路径，in-memory/noop 仅限显式测试。
+- 配置：`apps/api/config/development.toml`，正常 `awd.network_runtime = "helper"`；`noop` 仅供测试/mock。
+- 生产：API/PostgreSQL/Redis/RustFS/Caddy 由生产 Compose 承载（模板内嵌在 `scripts/install.sh`，安装后为 `$FLOATCTF_HOME/compose.prod.yml`，默认根 `/var/lib/floatctf`）；API 不发布宿主 9090，通过 external internal `fctf-platform-control`（API `10.42.8.2`）接收 FlagServer/JudgeServer 回调。生产 TOML 使用 Compose DNS。宿主只创建 `floatctf` 组（不创建该用户），API 容器以数值 `65532:$FLOATCTF_GID` 运行。
+- 修改 `crates/floatctf-helper/` / `crates/helper-protocol/` 后重新执行 `mise run setup`，刷新 root-owned `/usr/local/libexec/floatctf-helper`。