平台工程

平台工程索引

用途:搭建/维护知识库展示站与各类内容平台过程中,沉淀的工程方法、架构模式与踩坑。 与 AIGC 创作线并列——这里记的是「怎么把东西搭起来、部署上线、可持续维护」,不是「怎么创作」。

架构与模式

• 内容子项目构建时同步_独立仓库镜像进public_v1 —— 独立频繁更新的内容仓库:浅克隆→镜像进 public(排.git)→新内容自动上线、主仓不胖
• CI从Release抓二进制托管自有服务器_桌面应用国内直连下载_v1 —— CI 从 GitHub Release 抓 exe 进 dist→rsync 到香港服务器,给桌面应用做国内直连、零维护下载;二进制不进 git/Pages,固定文件名自动同步最新版
• ⚠️ 每日定时任务自动更新内容板块_首次自动化生产落地_v1 —— 首次自动化内容生产:定时任务只被允许「新增一个数据文件」,人先手动跑通一遍再交给定时器,并留「宁缺毋滥」不发闸门;后续已迁移云端并首次跑通,见连环坑复盘续篇
• 站内新版块五件套模式_三次复用与起刊两坑_v1 —— 新增内容版块的固定套路(数据源/内容集合/列表详情页/首页速览/全站导航),第三次复用(任务书版块)收敛;附 YAML 裸日期解析成 Date、机器人仓库 push 竞争两坑;07-24 补「状态机演进」:enum 扩容时取反式过滤(!== 'open')会静默吞掉新状态,分桶一律正向枚举 + 新态穿线所有渲染点
• ⚠️ 赛事状态机到点不切换_写入方不等于推进方_v1 —— 状态字段有人写、有人显示,却没人在到点时推进它(PB Arena 赛事永远停在建赛时的阶段);定位靠问「谁在到点改它」而非 grep 字段名,验收必须写成「不碰任何按钮等它自己变」;附「并列名词要逐项直达」「单用户复现的排版问题多是全员在临界点内侧」「状态机上线会追认存量数据」三条;结论已被同日续篇部分修正
• ⚠️ 零作品的比赛_界面演完不等于链路存在_v1 —— 上篇续篇兼修正(PB Arena):报名/进度条/倒计时全都在,7 场比赛 17 人次报名,submissions 表 0 行——界面演完不等于链路存在,验收要问「这功能跑完数据库该多出什么」再查表;附「补自动推进前先确认触发条件真的是时间(不是就交还给人)」「新链路复用既有实体只改阶段从哪来」「权威方从客户端搬到服务端后本地自算顺带触发的副作用会失灵」「修复被调用方提前赋值绕过(判据恒等)」四条 ⚠️首次
• ⭐ 静态站接账号系统_内容归git状态归库的双源切分_v1 —— 给 SSG 站加账号与「完全动态化」的状态,正解是切数据源不是升级渲染模式:正文归 git 走构建期、只把会变的字段交给数据库,构建期导出一份 JSON 清单给服务定时 upsert,前端客户端注水且失败即回落静态快照(nginx 没接通那段时间站点照常可读);附「视觉差异该由 CSS 承担而非 DOM 结构(否则跨状态重排要重建节点)」「scoped CSS 不覆盖 JS 注入的 DOM,会被注入的类名必须下沉全局」「登录墙架在钱前面不是门口」三条,以及 CI 幂等自举 + 四个只有真部署才现形的坑(.env.* 吞掉 .env.example、cp -a 重跑套娃、nginx sites-enabled/ 会加载目录下所有文件致备份撞车、enabled 是实体文件且与 available 早已不同步) ⚠️首次;本轮续篇见下
• 任务系统演进_站内新建管理台拆分首页瘦身_v1 —— 任务书从「写 md 才发」进化到「站内直接发」(source 列分流同步 + 动静两份详情页);调价独立于真相源(fee_override 同步不覆盖);管理台六页 + 共用壳 + 调价面板;笔记搬进 /notes/,首页 218→30 KB;滚动渐现抽共用模块 ⚠️首次
• ⭐⭐ 成稿链接存进库没人读_写入方不等于展示方_v1 —— 上篇续篇(蛛网之上):成稿链接三条写入路径、零条读路径——列、管理台输入框、接口 deliverableUrl 全在 07-28 就位,07-29 管理台拆分还搬过一次那个输入框,第一次有页面读它是 07-30 本轮;跨两轮没暴露是因为人一直在正文里手写「交付情况」替系统兜底;沉淀「写入方不等于展示方(存进库≠看得见;读路径要挂收敛字段 tasks.deliverable_url,不挂某条写入口的流水表 deliveries)」⭐⭐ 同族第三形态、「手工兜底掩盖系统缺口」⭐⭐、「upsert 两条分支的字段集要对齐(INSERT 有而 UPDATE 没有 = 只有第一次同步生效)」⚠️、「双源字段验收要造出『只有库里有』那一格」⚠️;附本机 chrome-headless-shell + --dump-dom 自测姿势(chrome.exe --headless=new 同参数会挂死)
• ⭐ 账号系统对标一线_多账号抽屉与外部通道半开陷阱_v1 —— 上篇同日续篇(蛛网之上):登录/注册/找回密码各自成页,本机多账号做成**「一柜多抽屉」+ 一个活跃指针**(切号换指针、退出只丢当前那把、令牌失效只丢挂掉那把、退出所有设备是显式动作),自助重置密码全链路;核心律=功能开关要接在「能力被验证过」上,不能接在「配置填了」上——发件域名没验证就填 key,页面照说「信已经发出去了」而一封没发,半开比关着更糟;附「防枚举的沉默与故障的沉默是同一种沉默→对外一句话、对内留全量」「断言测行为、截图测观感([hidden] 被自写 display 覆盖、三态硬塞进布尔致「登录中…」显示成红色错误)」「跨会话交接靠边界与判据而非步骤」三条 ⚠️首次
• 内测反馈渠道上线_匿名兜底与422探针验证_v1 —— 内测产品反馈渠道单会话上线(PB Arena):反馈入口必须匿名可用(“登录不了”正是最该被反馈的 bug,滥用靠双层限流不靠登录墙)+ 零迁移建表(全量 CREATE TABLE IF NOT EXISTS 惯例下加表=改常量)+ 422 探针线上验证不留脏数据 + 无框架存量库”模式考古先行”零返工

踩坑与验证陷阱

• ⭐ 全站文字截断体检_检测工具本身要先被证伪_v1 —— 体检脚本吐出的「缺陷清单」本身是待验证的假设(PB Arena 全站文字截断排查):判据里一个拍脑袋的箭头宽度常数把 8 个正常元素判成缺陷,还据此改了一处没坏的代码;标定法=先跑已知正常 + 已知损坏两个样本确认工具两端判对;附「能问浏览器就别自己算、且要问对问题」「误报会伪装成顺手修一下混进提交」「找同类问题按写法搜不按页面搜」三条 ⚠️首次

• ⭐ 构建产物的脏改动不是事故_复发是归因错了的信号_v1 —— kb-content 稳定出现 305 个未提交改动,连续两次被误判为「Obsidian 有损格式化事故」,真凶是自家 sync-content.mjs 的 normalizeFrontmatter()(设计行为:去 BOM/重排 tags/只留 tags+title);复发+上次已修=上次归因错了,比时间戳一分钟证伪(改动 18:00 vs 修复 16:44);附「写进记忆的错误归因会加速下一次误判」「查谁干的要点名册(obsidian.json)而非从 diff 形态反推」「派生物损坏≠源损坏」「问题在展示层就别修数据层」四条 ⚠️首次;处置=git.ignoredRepositories 让构建产物别出现在提交位

• ⚠️ 本地部署FastAPI静态站到3000端口_复盘_v1 —— 本地把 FastAPI + 静态站部署到 3000 端口的复盘:先看启动脚本和依赖，再把端口改成环境变量驱动，最后用 HTTP 200 验证访问链路

• ⚠️ 云端定时内容生产连环坑复盘_全绿不等于已发_v1 —— GitHub Actions 定时内容生产 6 连坑(schedule 不触发/OIDC/GitHub App/工具白名单/脏工作区/中转余额)与首次真实跑通;沉淀「全绿≠已发」「手动跑通会掩盖自动路径」「黑盒 action 先接可观测性」「换便宜模型≠更省」四律

• ⚠️ 双部署目标的base路径陷阱_根路径拼出双斜杠_v1 —— ${BASE}/${slug} 在根路径拼出 //slug 协议相对 URL 致全站内链失效;只在一个镜像现形

• ⚠️ 导出运行时无系统字体回退律_CJK豆腐块_v1 —— 桌面靠 OS 字体隐式补缺字形,Web/嵌入式导出无系统字体可借,拉丁字体画的中文全变豆腐块(桌面自测永远测不出);修法=给主力字体显式挂 fallbacks 把兜底固化进产物,零体积代价;附 headless 报错无细节须回编辑器 GUI 定位 + ETC2/ASTC 两坑(LastStand→Toy 验证导出实录)

• ⚠️ Claude预览环境不派发滚动事件_滚动类功能无法行为验证_v1 —— 预览 iframe 不派发 scroll/IO 事件 + 冻结动画时钟,滚动/动效类无法行为验证;退到验证公式/逐帧采样+真机抽测;07-16 补:交互面板 rAF=0(Konva 动画/hit 图/合成双击连环失灵)→ puppeteer 无头 Chrome 三层退级已产线化

• ⚠️ B站Toy同步事故复盘_版本指纹与外部cron兜底_v1 —— B站 Toy「无法同步更新」三环断裂(校验器误报/无 update 链路缺 id/线上停 v1)诊断实录;沉淀「版本指纹先定性」「校验器 ERROR 先复现解析逻辑」「沙箱 iframe 外部协议静默失效」「多镜像取最新」四条 + 「schedule 不可靠」升 ⭐⭐ 二次验证(外部 cron 兜底首跑即补救实录)

• ⚠️ 二维码载荷硬预算与最长真实载荷验证_v1 —— 扫码 URL 每字符都占码物理密度(中文 deflate 压缩率低,叙事全文是底盘);可选字段按硬预算逐级降配+码框位按长度自适应兜底;验证必须用最长真实载荷,调试捷径的短数据会系统性掩盖超限 bug(镜像自我扫码翻车实录)

• ⚠️ OpenAI兼容止于对话端点_多提供商视频接口分流与真key首测_v1 —— 「OpenAI 兼容」只兼容到 /chat/completions,视频端点三家三套(硅基 /video/submit、方舟 /contents/generations/tasks、OpenAI /videos)需按 Base URL 分流;模型名不许猜要拉列表,且 GET /models 默认列表常带分类过滤(视频模型要 ?type=video);附 flex 列压缩子项、可滚动面板内浮层被裁、错误文案截断掩盖诊断三坑(LibreCanvas 真 key 首测实录)

• ⚠️ OpenAI区域封锁与Worker就近执行陷阱_北美DO跳板_v1 —— OpenAI 区域封锁跟调用方 IP 走,CF Worker 就近执行等于没挂、Smart Placement 不救,钉区域唯一免费原语是 locationHint 的 Durable Object;含公开站零密钥同域中转的分层安全闸清单与「双端对照 10 分钟定性」迁移判据(镜像自我线上真 AI 收口实录)

账号与访问

• GitHub强制2FA小白处置_TOTP原理与离线生成器_v1 —— GitHub 强制 2FA(非收费);TOTP 纯本地算码不连外网,setup key 即密钥;手机/商店/扩展弹窗都受阻时,做单文件离线 HTML 生成器双击出码 + 恢复码双留底
• ChatGPT_Windows桌面版安装排障与账号合规边界_v1 —— ChatGPT Windows 安装失败四层排查:使用资格→Microsoft Store 分发→网络链路→账号会话;校正“403=风控”“全开旧TLS”“伪装时区/地区防封号”等过度推断
• ⚠️ ping通不等于路通_fake-ip假信号与节点带宽实测选型_v1 —— fake-ip 下 ping 是自问自答(解析到 198.18.x.x,ICMP 本机应答,节点挂了结果一样),永远绿的信号最没用;选节点不能看延迟——内置延迟测试只测握手,本次带宽垫底 2.72 Mbps 的节点延迟排第 8;附「运行态改了≠配置落盘(重启回滚)」「PS 5.1 按 ANSI 读 UTF-8 无 BOM 致中文标识符静默走错分支」两条 ⚠️首次 + named pipe 调 mihomo API;insight 3 是 全站文字截断体检_检测工具本身要先被证伪_v1 的跨项目二次验证

网页视觉与动效

• 🚧 网页主图logo流动动效迭代_液态变形与碎裂问题_v1 —— logo「整体液态流动」正解=feTurbulence+feDisplacementMap;当前 baseFrequency 偏高致「画面太碎」,待降频减octave(周一续修)。含抠图保色/contain自适应/SPA静态资源/reduced-motion豁免等可复用要点
• ⚠️ reduced-motion本机陷阱_动效降级纯淡入而非跳过_v1 —— Windows 关「动画效果」→全浏览器上报 reduce→尊重规范的动效本机全跳过,作者自测”毫无变化”(二次踩坑升律);正解=降级纯淡入(opacity 无位移安全)而非禁用;附滚动渐现完整模式(rv-on 渐进增强/animationend摘类还hover/IO错峰)+ headless 验证三坑(--blink-settings=prefersReducedMotion=false/虚拟时间口径/CSS被抽外部文件)
• 文档密集页两栏排版与对外截图脱敏_v1 —— 图多说明页塞窄栏竖堆致「又长又窄」,正解=加宽容器+图文左右两栏(minmax(0,…)+align-items:start)+窄屏回落单栏;附三纪律:对外截图「裁窗口外围>逐处打码」(authCode/组织名/内部wiki三类泄露点)、空状态给成型卡片、无头 Chrome 截图做静态视觉自检
• ⚠️ 美工改稿全站落地_跨稿重复才是规范_v1 —— 成套设计稿(30 张)全站落地(PB Arena 简洁低疲劳 V2):跨 ≥3 张稿重复出现的处理才够格当全局规范,单稿出现的按该页特例就地实现;附「规范文字不是待办清单,报缺失前先回读实现」「加派生字段前先数清有几条取数路径(后端分支故意绕开 normalize,只改 normalize 会本地全绿生产为空)」「宁可显示『没有』也不要用宽松日期解析猜一个错值」「要没有 padding 就别写 padding: 0,它会吃掉后续规则」四条 ⚠️首次;落地顺序=token 层全局改先行、逐页重排后置

关联

• 知识库网站免备案上线_香港轻量服务器方案 —— 站点免备案上线的服务器/CI 方案(现归在 04_方法论/06_协作运营,主题上属本类目)