从「部署一下」到一个能打开的网址

一、起因：一个 demo 卡在「只能在我电脑跑」

事情的起点很普通。

组里有同学写了个小工具——一个前端 demo，或者一个 AI agent，跑在自己 localhost:3000 上，想让团队其他人也点开看一眼。然后他卡住了。

要让别人能访问，标准流程是这样的：

对一个只是想「快速验证一下想法」的人来说，这六步太重了。从「我有个东西想给你看」到「这是网址你点开」，经常按周计。大部分 demo 还没走到这一步，就死在了「太麻烦」上。

我想要的体验其实很简单：

cd <project>          # 任意项目目录
claude                # 在 Claude Code 里说一句话
> 部署一下
                      # 1-3 分钟后:
                      # :rocket: https://my-app.example.com

一句话，1 到 3 分钟，拿到一个带 SSO + HTTPS 的网址。不写 Dockerfile，不碰 K8s，不配 DNS。这就是这个平台——我们内部叫它 iai——要解决的全部问题。

二、先看它最后长什么样

在讲怎么实现之前，先把全貌摆出来，后面讲链路才有坐标。

 开发者本机           平台节点                              Worker 节点

 ┌──────────┐        ┌──────────┐  ┌──────────┐
 │ Claude   │ ─API─▶ │ control- │──┤   PG     │           ┌────────────┐
 │ Code +   │        │ plane    │  │  MinIO   │           │ K3s agent  │
 │ Skill    │        ├──────────┤  │ Registry │           │            │
 └──────────┘        │ build-   │  │  Redis   │           │ user pods  │
                     │ service  │  │ user-PG  │ ← 自动开  │ (proj-xxx) │
                     └──────────┘  └──────────┘   给项目  └────────────┘

三块东西：

技术栈没什么花哨的：Go 1.22 chi pgxpool 做后端，React 18 Vite Tailwind 做管理后台，K3s 做编排，Keycloak 做 OIDC。选型的克制本身就是一个决策，后面会展开。

三、说「部署一下」之后，到底发生了什么

这是整篇文章里我最想讲清楚的一段。一次部署，从一句话到一个网址，链路是这样的。

Skill 端（你的电脑上）

你在 Claude Code 里说「部署一下」，Skill 的 push.sh 开始干活：

Control-plane（调度大脑）

一个 Go 进程，HTTP API + 一个后台 reconciler goroutine。reconciler 跑两个 loop：

第二个 loop 是后来加的，是被现实教育的结果。总有人手动 kubectl scale --replicas=0，总有节点驱逐、pod OOM 之后没拉起来。如果 control-plane 只在部署那一刻看一眼，DB 就会永远显示 running，而实际上应用早挂了。

Build-service

从预签名 URL 把 tarball 拉下来，跑 nixpacks——它会自动识别语言、生成构建 plan、产出一个标准化镜像，用户全程不需要写 Dockerfile。构建完 docker push 到本地 registry，然后把 deployment 推进到 pushing 状态，交给 reconciler。

K8s driver + Traefik 入口

deployer.go 是 client-go 的一层薄壳：给每个项目建独立 namespace proj-<slug>，写 Deployment / Service / Ingress，默认子域 <slug>.example.com。

流量入口是 Traefik，按 DaemonSet 部署、hostNetwork: true 直接绑每个节点的 :80 / :443。非 public 的项目自动挂上一条 middleware 链：

于是「未登录的人访问 → 自动跳 SSO 登录 → 登录完回到应用」整条体验就闭环了，应用本身一行认证代码都不用写。

四、几个我觉得值得讲的设计取舍

做平台的乐趣不在于「用了什么技术」，而在于「在每个岔路口为什么走了这条」。挑几个说。

为什么是 K3s，而不是托管 K8s

我们要在自己的 ECS 上跑。托管 K8s（EKS / ACK）不一定能方便地拉私有 registry、走内网，而且控制面是个黑盒。K3s 是单 binary、配置简单、控制面占用 < 1GB，单节点就能起步，扩容也平滑。对一个内部平台来说，「能完全掌控、能单机起步」比「云厂商托管」重要得多。

为什么 Traefik 用 DaemonSet + hostNetwork

云上的 ServiceLB 想拿公网 IP，得用 LoadBalancer 类型的 Service，公有云要另外计费。与其如此，不如让每个节点的 :80/:443 都能直接服务流量，DNS 轮询就是最朴素的负载均衡。hostNetwork: true 就是在说「我就要这台机器的 80 端口」，再配个 NET_BIND_SERVICE capability 让非 root 进程也能绑低端口。

为什么部署日志用 SSE，而不是 WebSocket

部署日志是单向的（server → client），SSE 完全够用。它走标准 HTTP，浏览器、curl、各种中间件兼容性都好。WebSocket 要多一层握手、要自己定协议，对一个单向日志流来说是过度设计。

为什么 OIDC 的 state 用 HMAC 签名，而不是存 cookie

OIDC 标准里 state 参数通常存 cookie 防 CSRF。但我们的 Web UI 和 Skill 是跨端口、跨子域的，cookie 的 scope 特别容易踩坑——这个子域写的 cookie，那个子域读不到。

所以这里把 state 做成 HMAC 签名的自包含字符串：所有需要的信息都编码进 state 本身，再用密钥签名校验，完全不依赖 cookie。副作用是它天然 stateless，对将来做 HA 也友好——任意一个 control-plane 副本都能校验，不需要共享 session。

用户应用的数据：共享底座，但每个项目「真隔离」

这是我最满意的一块。

用户在 manifest 里声明一句 postgres = true / redis = true / s3 = true，平台就自动开通对应资源、把连接串加密注入到 pod 里。业务方不用申请、不用配、不用自己想密码——但拿到的是真隔离的切片，不是一把共享钥匙。

我认真考虑过「每个项目一套独立 PG / Redis pod」，然后否掉了：

所有自动派生的环境变量都用 system=true 标记，后台不允许人工编辑——避免哪天 admin 手滑覆盖掉，把应用搞挂。值在数据库里用一个根密钥（KEK）加密落地，部署时解密注入到 K8s Secret，源码里不留任何明文。

运行时配置热加载

早期改 Keycloak 配置要改 .env + 重启容器，体验很差。现在所有可变配置都存在 system_config 表里，管理员在设置页保存 → PATCH 接口写库 → Runtime.Reload 刷新内存视图 → JWT 验签器通过 atomic.Pointer 原子热替换，零停机生效。

五、有意识地「没做」的事

平台的克制比平台的功能更需要纪律。几个明确选择不做的：

把「现在不做什么」写清楚，比堆一堆 feature 重要——它定义了这个平台是什么、不是什么。

六、关于扩容，留了后路

当前是单平台节点 all-in-one，能撑到团队大约 20 人、50 个项目。但好在每个组件之间从一开始就是网络解耦的：PG 走 URL，MinIO 走 S3 endpoint，registry 走 host:port。所以扩容基本不需要改代码，是纯运维动作：

单节点起步、但每一步都为下一步留好接口——这是我觉得做内部基础设施最该有的姿势。不要一上来就上 HA，但也别把自己焊死在单机上。

七、写在最后

回头看，这个平台真正解决的不是「部署」这个技术动作，而是「从想法到能给别人看」之间那段被流程吃掉的时间。以前按周计，现在按分钟计。

最让我有成就感的，反而不是某个具体技术点，而是当组里同学第一次说完「部署一下」、盯着终端里一行行滚出来的构建日志、最后看到那个 https://... 链接时——那种「居然真的就这么简单」的表情。

技术选型上我尽量克制：能用简单方案就不用复杂的，能单机起步就不提前上分布式，能复用底座就不每项目开实例。这些克制单看每一个都不起眼，但加在一起，就是「一句话拿到一个网址」和「折腾一周还没跑起来」的区别。