FelisMC/Felis
2
0 Fork 0
Code Issues Pull Requests 6 Actions Packages Projects Releases Wiki Activity
Files
f79e5ebb5eb7c557dc30085301d9a9beb9a1ec4f
Felis/AUDIT-2026-09-22.md
T

15 KiB
Raw Blame History

Felis 生产就绪审计 — 2026-09-22（真机 E2E + 混沌）

分支：audit-fixes-20260922（已推送）。环境：CentOS Stream 9 / aarch64 / k3s v1.36.4， IPv6-only 接入（ssh -6 -i ~/.ssh/id_ed25519 root@fdb2:2c26:f4e4:0:21c:42ff:fede:69ec）， 面板经 socat TCP6:443 → 127.0.0.1:30443 中继（手动启动，重启 VM 后需重开）。

已修复并验证（分支内）

# 缺陷 证据 修复
1 失败恢复后重试被静默吞掉：restore Job 固定名 + ErrAlreadyExists 一律当"幂等成功"；失败 Job 占名 10 分钟（TTL），期间重试返回 202 restoring 但什么都不跑 真机：坏 ref 制造失败 → 立刻合法重试 → Job 原地不动、无新 Pod k8sjobs.go：撞名时检查已完成（成功/失败）→ 删除+等 finalizer 释放（有界 10s）+ 重建；进行中仍幂等吸收。单测 3 个。真机复验：重试 4s 完成恢复
2 备份 Job 全部 FailedMount：Job 在 minecraft 命名空间挂 felis-config，而 bootstrap 只在 felis 命名空间创建该 Secret 事件：MountVolume.SetUp failed: secret "felis-config" not found felis setup 用既有 ensureSecretReplica 把 felis-config(felis.toml) 复制到 minecraft；VM 上手工复制后备份成功（167MB 归档）
3 RBAC 缺 jobs:get/delete（修复 #1 需要） Role 检查 APIMinecraftRole jobs → create/get/delete，测试同步更新
4 gofmt 9 文件漂移 + CI 无 gofmt 门禁；staticcheck 9 处 基线扫描 全部修复；CI 加 gofmt job
5 依赖漏洞：pgx v5.7.1（GO-2026-5004，可达 pgrepo.go）、x/net、x/text govulncheck 升 pgx v5.9.2 / x/net v0.55.0 / x/text v0.39.0
16 ConsumeLoginEmailOTP PG 实现与接口契约漂移：契约/fakeRepo 说「同 VerifyEmailOTP 生命周期（扣尝试/锁定/ErrOTPInvalid/ErrOTPLocked）」，PG 却是单条 UPDATE+ErrNotFound → 错码/重放/过期在 login 门、op-login finish、migration confirm 三个入口全部 500；且尝试次数永不累计、otpMaxAttempts 锁定失效 真机：login 门重放正确码 → HTTP 500；修复前错码不扣次。修复后复测：5 次错码 400 且 attempts=5（正确码因锁定也 400、码未消费）、新码可用、重放 400 pgrepo.go 改置为 VerifyEmailOTP 同构事务（FOR UPDATE、先锁后比、mismatch 扣次、match 消费），无 users 写副作用。提交 52549f7
17 ListPendingOpLogins PG 少列：接口注释承诺「joined to its staff username」，handler 输出 username/created_at，fake 正确填充；PG SQL 未 JOIN 也未取 created_at → 真机 pending 列表 username 为空、created_at 为 0001-01-01 真机 internal /op-login/pending 响应 pgrepo.go SQL 改为 JOIN users + 取 created_at。提交见分支
18 绑定码并发兑换 500：RedeemPlayerBindCode 无 FOR UPDATE（同文件 VerifyLinkCode 有），且裸 INSERT。6 路并发同码兑换 → 3×HTTP 500（users_username_key 唯一冲突）+ 1×400 + 2×200；跨码并发同 UUID 同样会撞 真机四组并发测试 + API 日志 unmapped error ... duplicate key 同码：码行 FOR UPDATE（输家干净地 400 invalid_code）；跨码：INSERT users ... ON CONFLICT (username) DO NOTHING+重读、account_links ON CONFLICT (mc_uuid) DO NOTHING（两路汇聚同一 user）。复测：同码×6=1×200+5×400、双码×2=2×200 同 ID、DB 干净、日志零 unmapped
19 reaper CronJob 渲染位置错误，永远无法调度：felis manifests 把 CronJob 渲染到控制 ns，却引用 minecraft ns 的备份 PVC（Pod 不能跨 ns 挂 PVC：真机 FailedScheduling: persistentvolumeclaim "felis-backups" not found）；修正 ns 后又发现 ServerAccount 也不能跨 ns 使用（serviceaccount "felis-reaper" not found）。而 reaper 的 Role/RoleBinding 本就在 minecraft ns 真机三层取证（PVC/SA/调度） CronJob 与 SA、RoleBinding subject 全部移到 MinecraftNamespace（提交 e4f2cff+c839454）。修复后完整演练通过（见下）
6 默认安装无备份能力 + 回收链路不可达/不可用：(a) 没有任何环节渲染归档 PVC，FELIS_BACKUP_PVC 永远为空 → backup/restore 恒 503；(b) bootstrap 从不下传 reaper 三旗标 → 官方安装路径根本无法启用回收；(c) 即便启用，stock k3s 的 <root>/<pvc> 布局不存在，且 k3s storage root 是 0700 root:root、reaper pod 以 uid 1000 运行 → 真机 lstat /worlds/…: permission denied（fail-closed 跳过，但纯空转）；(d) README 口径（“定时备份”）不实 真机全链路：默认渲染 PVC+env → 建服→marker→备份 202→jobs 端点 running→succeeded→改 marker→restore→读回原值 ✅；再建 resolvecheck 世界（20d idle，marker）→ CronJob 手动 Job：evaluated=2 reaped=1，归档含 marker、PVC+宿主目录回收、world_backups 得 inactive_15d 行、servers 行/CR 保留 ✅ platform/workloads.go 渲染归档 PVC（minecraft ns、RWO 10Gi、默认 SC），felis manifests --backup-pvc 默认 felis-backups（= 空为显式关闭），bootstrap 统一下传 env/旗标并写 [archive] local_path；resolveWorldDir 新增精确 local-path 目录解析（读 PVC spec.volumeName，非 glob，杜绝陈旧 PV 目录顶替）；ReaperRole 增 pvc:get；bootstrap 设 FELIS_WORLDS_HOST_PATH 时给 uid 1000 授 traverse（setfacl/o+x）；README/故障手册改写。提交 fd33fd0+2b87a5a
8 磁盘打满灾难链：DiskPressure → kubelet 驱逐控制面（无 PriorityClass 保护）→ 镜像被 GC（无外网、registry 空）→ 全部 ImagePullBackOff；释放后数分钟才恢复调度。恢复依赖人工 `docker save k3s ctr images import -` 三轮真机 drill（原缺陷复现 + 两轮修复验证）：①自定义 1e6 类：游戏 pod 先走、控制面随后仍被驱逐（kubelet 日志逐条列出 ranked/evicted），随后镜像被 GC → ErrImagePull；②内建 system-cluster-critical（2e9）：填盘至 1.7G free，kubelet 对 felis-api/operator/registry 全部报 “cannot evict a critical pod”，三者在整个 DiskPressure 期间保持 Running；游戏 pod（0）被驱逐；③释放磁盘后：DiskPressure 经 ~5 分钟（eviction-pressure-transition-period）转 False——即“恢复慢”的主因；被 GC 的游戏镜像按 runbook 重导入后 25s 恢复 ✅
9 升级策略 Recreate：单副本 + Recreate：任何控制面升级=停机；坏升级（错 tag）中断约 95s 且需人工 rollout undo（无自动回滚） 复核部署模板（Recreate + 单副本 + 无 leader election 的注释理由成立） 不改策略（Recreate 是对无 leader election 的正确取舍），改为固化 runbook：troubleshooting §15 = 升级即重跑安装器；停机窗口=rollout 时长；坏镜像在安装器 180s 等待内以 kubectl describe 诊断呈现；回滚 kubectl rollout undo（镜像被 GC 时先按 §13b 重导入）。提交见下
10 备份语义：归档包含整个 /data（jar、libraries、cache），167MB；是否符合 world backup 定位待评估 真机 tar 清单（cache/、config/、eula.txt、server.properties、jar）+ 恢复语义（overlay+prune） 评估结论：整卷备份是正确语义（回滚=整服状态回滚，含配置/插件），保留行为；文档化：troubleshooting §10「backup contains」+ OpenAPI/README 口径改为“整服数据卷”。提交见下

待决策台账（未修）

# 主题 说明
7 异步失败不可感知 backup/restore 失败后无状态出口：restore 行不变、backup 无行；只有集群侧 Job/日志可查。建议状态字段或 ?failed 查询
11 PG 断连表现 会话查询失败报 401 而非 503（fail-closed 但误导；用户以为没登录）
12 ready 门滞后 容器 Ready 后 6~10s 内 API 仍 409 not_running
13 setup token 截断 43 字符 token + 长域名，80 列终端下 TUI 截断显示（复现：tmux 80 列）
14 日志噪音 controller-runtime 未 SetLogger，首用打印整段堆栈；TLS handshake EOF 噪音（kubelet 探针）
15 reaper 启用未演练 已演练完毕（2026-09-22）：绑定挂载演练 world → 一次 pass 归档+删 PVC+保留 servers 行/CRD；过期归档驱逐（行转 deleted、文件删除、合法归档未动）。启用仍受 #6 三旗标约束；另注意 --worlds-host-path 的 <path>/<pvc> 布局在 stock local-path 下不成立（编排责任），且 VM 上演练用的 CronJob 已 suspend 防误删（真实世界目录不在 /srv/worlds-root）

已验证事实（正向清单）

  • 安装→hook 发码→Owner 绑定→passkey（虚拟认证器）→面板管理员全链路 ✅
  • 建服（POST /servers）→ 唤醒（operator 拉 StatefulSet pod）→ RCON list → SSE 控制台 → 停止 ✅
  • 文件编辑：列目录/读/写（wire 为 base64）/256KiB 413/路径穿越 5 变体全拦截/运行中 409 ✅
  • 备份→篡改→恢复数据演练：v1→备份→v2→恢复→读回 v1 ✅（G2 数据可恢复）
  • 毒档案 fail-closed：穿越/绝对路径/符号链接条目 → archive entry escapes target 退出码 1，零写入 ✅
  • 混沌：PG 掉线（healthz 仍 200、恢复后连接池自愈）、API pod 击杀（~2s 中断）、整机重启（32s 回归、会话/CRD/停止态全保留）✅
  • felis update 报告（k3s/velocity 有更新、私有仓库 404 优雅处理）✅
  • 账户全套真机 E2E：绑定码新玩家注册（幂等/并发见 #18）、邮箱验证（onboarding 门）、邮箱 OTP 登录（错码扣次/5 次锁定后正确码也 400、重放 400、staff 账号 403 拒绝）、Passkey 注册+discoverable 登录+邮箱优先登录（虚拟认证器；Chrome 要求 Page.bringToFront 才能过 focus 检查）、登出吊销会话（旧 cookie 401）
  • op-login 全状态机（start→status→approve→finish；早 finish 不烧码、错码扣次且请求保留、重放/重复批准/非管理员批准/未知 handle 全部按契约返回）✅
  • 并发：OTP 风暴 8 路 = 1×202 + 7×429 且仅铸 1 码；绑定码并发（同码/双码）见 #18 ✅
  • reaper 全链路真机演练（修复 #19 后）：绑定挂载假世界 → felis reaper 一 pass：归档 tar 落盘（内容含标记文件）、world_backups 行 inactive_15d+90d 过期、PVC 删除且宿主目录回收、servers 行保留且 activity 时钟重置（红线②）、CRD 保留；第二 pass：伪造过期归档被驱逐（expired=1，文件删、行转 deleted），合法归档未动；evaluated=2 reaped=1 只动到期的世界 ✅

本轮新增真机证据（第二日）

  • 默认安装的备份闭环：apply 新 bundle → 归档 PVC 自动创建（WaitForFirstConsumer，被首个 backup Job 拉绑定）→ POST /backup 202 → GET /jobs running→succeeded → 漂移 marker → restore-backup → 读回备份前内容 ✅
  • 回收闭环（真实 k3s 布局 + 权限）：resolvecheck（20d idle）→ CronJob 派 Job：evaluated=2 reaped=1；归档含 marker、PVC+宿主目录回收、world_backups 记 inactive_15d；期间先经历 lstat /worlds/…: permission denied（k3s storage root 0700）→ 修 ACL/root 权限后通过 ✅
  • 磁盘压力三连 drill：①1e6 自定义类：游戏 pod 先走、控制面随后仍被逐（kubelet ranked/evicted 日志）→ 镜像 GC → ErrImagePull；②改内建 system-cluster-critical 后：cannot evict a critical pod × felis-api/operator/registry，全部保持 Running；③恢复阶段实测 DiskPressure 条件 ~5min（eviction-pressure-transition-period）转 False，被 GC 的游戏镜像按 runbook 重导入后 25s 恢复 ✅
  • 混沌：SIGKILL k3s 主进程 → kubectl 与 felis-api ready 均在 10s 内恢复（api pod 本身未被重启）✅；内存压力（2.6G tmpfs 满写）：无 OOM kill、无人被逐（swap 5.9G 吸收 + 内核回收），控制面不受影响 ✅
  • 构建链路定位（未修，见下一节）：Kaniko/Trivy 默认镜像是外部的 → 已加 [registry] kaniko_image/trivy_image/build_cpu_limit/build_mem_limit 覆写；上下文跨 ns 不可挂载（PVC 不能跨 ns）是设计级缺口，s3 lane 也缺凭据注入 ✅（证据：internal/submit/blobstore.go:40、cmd/felis/api.go contextBase 分支、jobspec 无 volumes/env）

结论：离"生产可用"还差什么（按优先级）

  1. 构建链路的上下文通道（唯一的功能级缺口）。用户模组提交 → 审批 → Kaniko 构建这条 lane 需要跨命名空间传递 context 的机制；PVC 不能跨 ns，s3 lane 又缺 build pod 侧凭据注入。两条候选：a) 官方走对象存储（在 bundle 里加 MinIO 或让 operator 配外部 S3 + 为每次构建挂 per-build Secret + netpol 放行 endpoint）；b) 在 felis-build 里做 context handoff（一个控制面任务把 blob 落到 build ns 的 PVC）。做 a) 时顺带把 kaniko/trivy 镜像推入内建 registry。
  2. 镜像耐久：kubelet 仍可能 GC 掉"当前无人使用"的镜像（游戏镜像已实测发生）。把控制面与游戏镜像推入内建 registry 并让 Deployment/StatefulSet 引用 registry 路径，可免去"事故后人工重导入"。本轮已用 runbook（troubleshooting §13b）兜住。
  3. PG 级契约测试：PGRepo 与接口/fake 漂移已抓到 3 例（#16/#17/#18）且单测全绿也发现不了；建议对"注释承诺了字段/错误码/生命周期"的方法加 Postgres 集成测试。
  4. 面板把 /jobs 显示出来：API 已有出口（#7），ServerBackups 页加一块"最近操作"即可让普通用户看见失败原因。
  5. 多节点回收：reaper CronJob 无 nodeSelector，多节点需按卷所在节点加 selector（代码与文档均已标注，未实现调度约束）。
  6. 告警：felis_* 指标已全有生产者，但无非告警；磁盘/内存阈值告警建议随部署一并给出。

系统性观察

  • PGRepo 与接口契约/fake 漂移（#16/#17/#18）：fakeRepo 与接口注释是对的、PG 实现在细节上落后，单测全绿也发现不了。建议后续引入 PG 级契约测试（testcontainers 或针对关键写路径的集成测试），重点覆盖「接口注释承诺了字段/错误码/生命周期」的方法。
  • 部署知识：交叉编译必须先把 panel/dist 拷进 internal/panel/static 再 go build，否则镜像内 SPA 缺失（页面显示 “assets were not built”）。本批镜像为 felis:auditfix7。

复现入口速查

  • 面板会话 cookie：/tmp/felis-cookies.json；API 助手：/tmp/fcurl.sh
  • 测试服：test-one（minecraft ns，stopped）；合法备份 bk-47ee2e7e96e5a4ca9d0e51b805518bac
  • CDP 调试口：Mac 127.0.0.1:9333（独立 Chrome，profile /tmp/felis-chrome2）；WebAuthn 虚拟认证器需在同一 CDP 会话内完成仪式，且先 Page.bringToFront（否则 NotAllowedError: page does not have focus）
  • 分支已部署到 VM：felis-api 镜像 = felis:auditfix7（含全部修复）
  • VM 内部面：k3s kubectl -n felis port-forward svc/felis-api-internal 18081:8081（Pod 重建后转发会悬死，需重启）；reaper CronJob（minecraft ns）已应用但 suspend=true
Reference in new issue View Git Blame Copy Permalink