本页目录展开
  1. 组容器
    1. 创建:先规范名字,再查重
    2. 规格:limits 是上限,requests 是估算
    3. 生命周期:scale 0 不是删除
    4. 文件、日志与终端
  2. 部署
    1. 从 Git 到 supervisord
    2. 自定义脚本:校验的是路径,不是文件名
    3. Webhook 与部署队列
  3. 网络与存储
    1. 子域名:五道校验
    2. frp 隧道与 nginx 托管块
    3. 凭证下发
  4. 资源治理
    1. 指标采样
    2. GPU 与压力驱逐
    3. 巡检、配额与预测
  5. 计费与告警
  6. AI、审批与安全
  7. 面试速答

集市云(Cloud)是面向软工同学的自助算力平台:一个「组」就是 K3s clouds 命名空间里的一个 Pod,用户拿到 root,可以在里面跑服务、申请数据库和对象存储、绑定子域名。它解决的是「想部署点东西,但不想先学一整套集群」的问题——申请、网络、配额、计费都收在一个网页里。平台自己是 Flask + gunicorn(单 worker,SocketIO 需要粘性会话)加 React SPA,仓库是 yatterra:web/ 后端、web/frontend/ 前端、manifests/、systemd/。下面按组容器、部署、网络与存储、资源治理四块讲实现和踩过的坑,最后补计费、AI 与审计。

组容器

核心约定只有一句:一组一 Pod。组的状态写在 groups.json,K3s 只承载运行态。这样即使集群被清空,按状态文件也能把全部组重建出来;反过来,任何只改集群不改状态文件的操作,下一次 reconcile 就会丢。

创建:先规范名字,再查重

用户在页面上填组名、选规格(CPU / 内存 / 存储 / GPU 卡数)、选类型(Linux / Windows / Android)、选节点(默认 auto),提交后平台做四件事:把组名规范化为小写 RFC1123 名称;按类型补齐缺省规格;确定节点;写状态文件再渲染 Deployment 并 apply。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# web/groups.py
def create_group(name, gpus=None, cpu=None, mem=None, storage=None,
type=None, node="auto", image=None, mounts=None, ...):
name = normalize_name(name) # 必须是小写 RFC1123:[a-z0-9-]
state = load_state()
if name in state["groups"]:
raise ValueError(f"组 {name} 已存在")
is_windows, is_android = type == "windows", type == "android"
if is_windows or is_android or not node:
node = "auto" # /dev/kvm 与 VM 磁盘只在默认节点
if node != "auto" and not nodes.valid(node):
raise ValueError(f"未知节点: {node}")
is_gpu = bool(gpus) and not is_windows and not is_android
if cpu is None:
cpu = (ANDROID_DEFAULT_CPU if is_android
else WINDOWS_DEFAULT_CPU if is_windows
else DEFAULT_GPU_CPU if is_gpu else DEFAULT_CPU_CPU)

几个坑都出在这段的顺序和缺省上。

  • 规范化必须在查重之前。 Demo 与 demo 规范化后同名,先查重会漏判,最后两个组抢同一个 k8s 资源名。名字不合法时 kubectl apply 还会拒绝,留下孤儿 manifest 和 home 目录,所以校验要前置。
  • Windows / Android 组强制 auto。 它们依赖的 /dev/kvm 与 VM 磁盘只在默认节点上,允许用户选别的节点只会得到起不来的 Pod。
  • 按类型的默认规格不同。 GPU 组、Windows 组、Android 组各有一套默认 CPU / 内存,不能一刀切。

规格:limits 是上限,requests 是估算

创建时填的 CPU / 内存是上限,写进 Deployment 的 limits;requests 不由用户填,而是按历史用量估算。这样调度器按真实占用算账,用户仍然可以在短时间内突发到上限。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# web/req_estimate.py
def request_for(g):
limit_cpu = parse_cpu(g.get("cpu", "1"))
limit_mem = parse_mem_gi(g.get("mem", "1Gi"))
limit_storage = parse_storage_gi(g.get("storage", "1Gi"))
e = load_state().get(g.get("name", "")) or {}
storage_req = fmt_storage_gi(min(limit_storage, FLOOR_STORAGE_GI))
if e.get("cpu_ewma") is None or e.get("samples", 0) < 3:
cpu_req = fmt_cpu(min(limit_cpu, max(FLOOR_CPU, limit_cpu * DEFAULT_REQ_FRACTION)))
mem_req = fmt_mem_gi(min(limit_mem, max(FLOOR_MEM_GI, limit_mem * DEFAULT_REQ_FRACTION)))
return cpu_req, mem_req, storage_req
eff_cpu, eff_mem = eff_cpu_mem(e) # 有效用量取 EWMA 与 p90 的较大者
cpu_req = fmt_cpu(_target_cpu(eff_cpu, limit_cpu))
mem_req = fmt_mem_gi(_target_mem_gi(eff_mem, limit_mem))
return cpu_req, mem_req, storage_req

样本不足 3 次时,取「上限 × DEFAULT_REQ_FRACTION」并设下限;样本够了才用 EWMA(实际是 EWMA 与 p90 取大)。

  • requests 只在 Pod 重建时算,运行期不热改。 否则每次采样都会触发滚动更新,容器被反复重启。
  • hostPath 的字节数不能当 requests。 存储由宿主机目录提供,Kubernetes 不把它计入 ephemeral-storage,写进去只会让调度器误判。
  • 两者相等会把利用率钉在低位。 requests 决定调度与驱逐优先级,limits 决定 cgroup 上限;相等就没有超卖空间。

生命周期:scale 0 不是删除

启动、停止、重启、删除四个按钮全部映射到 Deployment 的副本数与滚动重启:停止是 replicas=0,保留 home 卷;删除才会清掉 Deployment 和 home 目录。接口层用 @api_pod("owner") 做权限,每个动作落一条审计。

1
2
3
4
5
6
7
# web/api/pods.py
@pods_bp.route("/<name>/stop", methods=["POST"])
@api_pod("owner")
def stop_pod(name):
res = lifecycle.stop_group(name) # scale replicas = 0,保留 home 卷
audit.record("api_stop_pod", detail=name, actor=_actor())
return jsonify(res)

界面文案必须把「停止」和「删除」区分开——两者视觉相似,后者会连数据一起清掉。

迁移节点时,共享盘只改 g['node'] 在新节点启动,不复制不删除;loop 支持的 data.img 在源节点卸载、目标节点挂载,保证同一时刻只有一个节点持有 ext4;其余情况走 SSH 传 home 与 data.img,只有目标节点启动成功才删源目录,失败则回退原节点重启。改名要同时改三处:状态文件、frpc 代理名、nginx server_name,漏一处就是「组还在但域名 502」。重置密码改 Deployment 的 CLOUD_PASSWORD 环境变量并触发滚动更新。

文件、日志与终端

网页可以浏览组内文件、在线编辑、上传下载,也能对代码库做结构索引、符号查找和全文检索。文件接口走 Pod 的 home 目录,路径先 os.path.normpath 再做前缀校验,挡住 ../ 越界;在线编辑还必须限制单文件大小和后缀白名单,否则编辑接口会变成任意文件写入通道。代码索引由 podcode.py 定期重建,生成大纲、符号表和向量索引,搜索基于 hostPath 上已建好的索引。

日志和 Web 终端走 kubectl logs -f / exec,转成流式响应给前端。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# web/api/pods.py
def stream_logs(name):
pod = deploys.resolve_pod(name)
if not pod:
return jsonify({"error": "Pod 未运行"}), 404

def _stream():
args = ["kubectl", "-n", groups.NS, "logs", "-f", "--tail=100", pod]
yield from _iter_log_process(args)

resp = Response(_stream(), mimetype="text/event-stream")
resp.headers["Cache-Control"] = "no-cache"
resp.headers["X-Accel-Buffering"] = "no" # 关掉 nginx 缓冲,否则日志被攒住
return resp

流式连接要设空闲超时,并在客户端断开时释放 exec 进程,否则每次断线都会在 Pod 里残留一个 shell。

另有一个临时端口代理:用户想直接访问组内 8080 之类还没绑域名的服务时,平台按 pod + port 反代到 Pod IP。限制是成员及以上、只做 GET/HEAD、只打到该 Pod 自己的 IP、响应体上限 16MB 超限截断。

部署

从 Git 到 supervisord

用户填仓库地址与分支、选组、选启动方式,平台依次做:validate_repo 校验地址(只接受 http(s) / git)、浅克隆到工作目录、按 deploy.sh 或自动识别(Python / Node / Go)生成启动命令、注册到 supervisord(崩溃自启、开机自启)、把运行记录写入部署表。克隆必须限定深度,全量克隆大仓库会把超时预算耗在下载阶段。

并发用文件锁兜底:同一部署记录同时只跑一个。run() 的 wait=True 让 push-to-deploy 排队等待;skip_if_same_ref=True 在 ref 未变化且程序 RUNNING 时跳过重启,让重投幂等。

自定义脚本:校验的是路径,不是文件名

用户也可以直接填 deploy.sh 的绝对路径让平台执行。校验规则三条:必须是绝对路径、不能含 ..、必须在 /home/cloud/ 或 /shared/ 下。

1
2
3
4
5
6
7
8
9
10
11
12
# web/deploys.py
def validate_script(path):
p = (path or "").strip()
if not p:
return False, "脚本路径不能为空"
if not p.startswith("/"):
return False, "脚本路径必须是绝对路径"
if ".." in p.split("/"):
return False, "路径不能含 .."
if not any(p.startswith(pre) for pre in _SCRIPT_PREFIXES):
return False, "脚本路径仅允许 /home/cloud/ 或 /shared/ 下"
return True, ""

这三条挡住的是「写 /etc/cron.d/x 让平台以 root 执行」这类路径。按文件名或后缀校验挡不住 .. 和软链,校验点只能落在规范化后的路径白名单上。

Webhook 与部署队列

Webhook 有两种密钥作用域:全局密钥可以触发任意「仓库 + 分支」匹配的部署;单部署密钥只能触发它自己那条记录,泄露后影响面被限定。验签必须对原始 body 做,不能在 JSON 解析再序列化之后做——字段顺序一变,签名永远对不上。

GPU 组允许多个小任务并行。defer_queue.py 记录待执行项,scheduler.py 决定落在哪张卡:place_train 先按节点过滤组可见的卡,再在剩余显存够用的卡里挑负载最低的;没有可用卡就返回 None,由调用方排队。卡内用 MPS 按百分比切分算力,set_mps_pct 把百分比写回分配记录,作为下一轮重平衡的 diff 基准。只改运行态不落库,重平衡会反复重设。

网络与存储

子域名:五道校验

用户填子域名和容器端口,保存后一分钟内公网可访问。一条映射要连过五道:子域正则(1–63 位小写字母数字连字符)、保留名黑名单、端口范围、端口黑名单(集群内部服务端口)、唯一性(子域不与已有映射重名、端口不被其他映射占用、不与现有 nginx server_name 冲突)。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# web/proxy_map.py
def add(subdomain, port, note="", pod=None):
sub = (subdomain or "").strip().lower()
if not SUB_RE.match(sub):
return False, "子域只允许小写字母数字和连字符,1-63 字符"
if sub in RESERVED:
return False, f"子域 {sub} 是保留名,禁止"
port = int(port)
if not (1 <= port <= 65535):
return False, "端口范围 1-65535"
if port in BLOCKED_PORTS:
return False, f"端口 {port} 是集群内部服务端口,禁止映射到公网"
state = _load()
if any(m["subdomain"] == sub for m in state):
return False, f"子域 {sub} 已存在"
if any(m["port"] == port for m in state):
return False, f"端口 {port} 已被其他映射占用"
...

端口黑名单最容易被忽略:放通 kubelet 或内部 API 端口,等于把控制面直接暴露到公网。临时端口代理也共用这份黑名单。

frp 隧道与 nginx 托管块

Pod 只监听内网端口,公网流量走 frpc → frps → 本机 nginx。frpc 配置和 nginx 站点都由代码生成,并且用标记块包起来,重写时整块替换,而不是逐条增删。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# web/groups.py
def frpc_segment(name, local_port, remote_port):
return f"""[[proxies]]
name = "{name}"
type = "tcp"
localIP = "127.0.0.1"
localPort = {local_port}
remotePort = {remote_port}
"""

def build_managed_block(state):
lines = [FRPC_MARK_BEGIN]
for g in state["groups"].values():
lines.append(frpc_segment(f"grp-{g['name']}-ssh", g["ssh_nodeport"], g["ssh_public"]))
lines.append(frpc_segment(f"grp-{g['name']}-web", g["web_nodeport"], g["web_public"] - 10000))
lines.append(FRPC_MARK_END)
return "\n".join(lines)

重写 nginx 前必须先清掉旧的 listen 23xxx ssl 块,否则每改一次映射就多一份 server 块,nginx 启动直接报 duplicate listen。「标记块 + 整块重写」把配置生成收敛成一个纯函数,天然幂等。

凭证下发

组可以申请 MySQL / Redis / MinIO,db_svc / minio_svc 按组创建 database 与 bucket,签发只对该资源有效的账号,凭证可查看、可吊销。吊销必须同步改数据库授权,不能只删平台记录,否则平台上显示「已吊销」,实际账号还能连。

资源治理

指标采样

fleet_sampler 定时采本机与远程主机指标写 SQLite,metrics.py 提供聚合查询给前端画曲线。采样进程靠文件锁保证全局只有一个写者:

1
2
3
4
5
6
7
8
9
10
# web/fleet_sampler.py
def main():
parser.add_argument('--interval', type=int, default=15)
if args.interval < 5:
parser.error('interval must be at least 5 seconds')
store = Store()
with open(store.path + '.lock', 'a') as lock:
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB) # 抢不到锁就退出
while True:
sample_once(store, interval)

采样表必须写死保留期并定期清理。SQLite 长到几 GB 后,查询会拖慢整个平台。

GPU 与压力驱逐

每个 GPU 组只能看到分配给它的卡(NVIDIA_VISIBLE_DEVICES),算力再用 MPS 百分比切。要清楚这只是两层最小实现:可见性隔离不约束算力,MPS 才约束算力;两者都要有。

机器紧张时,低优先级组的任务被暂停,压力缓解后自动恢复。每轮读压力信号、按 tier 构造候选、驱逐,并记录 low_since 做滞回恢复。

1
2
3
4
5
6
7
8
9
10
11
12
# web/priority_kill.py
def cycle(dry=False):
p = read_pressure()
if p is None:
return # 无信号,fail-safe:不动作
st = load_state()
top = pod_usage_by_group()
cands = build_candidates(p, top, gpu_total_mem(), st)
n_evict = do_evict(cands, st, dry)
n_recov = do_recover(p, st, dry)
if n_evict or n_recov or cands or st.get("stopped"):
save_state(st)

恢复必须带滞回:low_since 持续低于阈值一段时间才恢复,否则会在阈值附近反复驱逐—恢复,形成抖动。读不到压力信号时选择「不动作」,也是同一个方向——按默认值动作只会放大抖动。

巡检、配额与预测

  • Pod 巡检:podwatch.scan_one 扫描 home 目录、做 diff、更新 profile,单次扫描异常只记日志不外抛。巡检函数一旦抛异常,整个巡检线程退出,所有组一起失去监控。
  • 硬盘配额:按组统计 home 占用,hdd_quota.ensure 在组所在节点建带容量上限的磁盘镜像(远程节点走 SSH,超时 900 秒),超限时限制写入;删除组先解挂再清理。
  • 容量预测:forecast.predict_supply 对历史序列做 STL 分解(趋势 + 季节 + 残差)预测未来供给,给出低谷窗口排重任务。历史不足或序列全零时退化为不建模,并标记 dead-column;结果带误差分位和回测。只给点估计的预测没法用来评估排产风险。

计费与告警

计费的基本单位是「分」,全链路整数运算。钱包是账户 + 流水两张表;组间转账时两条流水共享同一个 token,token 上有唯一约束,重放同一请求返回空而不重复扣款。

1
2
3
4
5
6
7
8
9
10
11
# web/wallet.py
def transfer_to_pod(group_name, username, amount_cents, *, token, note="", actor=""):
"""Atomic and exactly-once: both ledger rows share token (UNIQUE)."""
billing_store.ensure_account(group_name)
ensure_account(username)
cents = int(amount_cents)
if cents <= 0:
raise ValueError("分配金额必须为正")
with billing_store.tx() as cn, cn.cursor() as cur:
# 同一 token 写两行(转出 / 转入);唯一约束保证重放不产生第二次扣款
...

幂等靠唯一约束,「先查再插」在并发重试下必然漏。

用量按 tick 采 cgroup 数据累加:take_tick 是纯函数(不算库),由调用方统一落库;两次 tick 间隔异常(比如进程被挂起几小时)时退回固定间隔,避免一次长暂停把用量算爆。计费口径上,每个资源键独立四舍五入,总额等于各键之和,保证「账单明细之和 = 账单总额」——总额单独舍入一定会对不上。

充值下单走支付网关,回调按 out_trade_no 幂等入账,再按小时结算。结算只处理已完整走完的小时,平台内部组免计费。回调可能重复到达,入账前必须查重,否则一次支付能充两次。

告警这边:PWA 推送以 event_key 作 SQLite 主键做去重,同一事件只推一次,收件人按组成员关系计算;去重键要包含「事件 + 对象 + 时间片」,只用事件名会把后续真实告警一起吞掉。证书告警定时探测配置域名的 notAfter,剩余天数低于 CERT_WARN_DAYS 时推管理员,每张证书只推一次。主机巡检分磁盘、swap、GPU 温度、守护进程、集群五类,任一检查抛异常只记录并跳过;告警要有静默窗口(BUCKET_S),否则同一块盘持续高位会把通知渠道打满。

AI、审批与安全

平台内置对话助手,run_agent 是生成器,按事件流式输出文本、工具调用、工具结果和压缩事件,模式分 ops(运维)与 build(构建)。助手用的是调用者身份,工具调用必须过 agent_required_perm,权限判定不能省。

知识库 RAG 的文档切块入 Qdrant,检索时按权限选集合:kb_public 对所有人,kb_ops 只对具备 infra.* / ops.* 权限的人,结果合并后按分数排序。

1
2
3
4
5
6
7
8
9
10
11
# web/kb_service.py
def retrieve(query, user, k=DEFAULT_K, min_score=DEFAULT_THRESHOLD):
query = (query or "").strip()
if not query:
return []
vec = embed([query])[0]
hits = []
for coll in collections_for(user): # 权限在召回阶段就分流
out = _qdrant("POST", f"/collections/{coll}/points/query",
{"query": vec, "limit": k, "score_threshold": min_score})
...

权限过滤放在召回阶段,不能放到生成阶段:生成阶段过滤只能保证「不说」,不能保证「没读到」。

IDE Agent 用 JSON Schema 声明工具,模型自己挑。pod_bash 以 cloud 用户在组内执行,默认超时 60 秒(最长 120 秒),输出截断在 30k 字符,有副作用的命令要用户确认。写文件和执行命令必须落在组的 home 目录内,越界就是提权。浏览器助手管会话的启动、停止与流式输出,单条消息限制 8000 字符。

高危操作走审批闸 gate():先 classify 分类,需要确认就登记 pending 并返回「已挂起」,否则返回 None 直接执行。挂起后要能通过 verify_pending / resume_approved 恢复执行,不然批准了也不会继续。分类过程异常时选择「放行 + 记审计」,因为还有 denylist 兜底——这个方向取决于兜底是否可靠,不能照抄。

成员只有 owner / member 两级,邀请和加入都落审批记录。审计每次操作追加一行 JSON,actor(操作者本人)与 module(子系统动作)二选一,模块动作会把真实操作者以 by= 写进 detail。登录有 UniSSO 与集市 OAuth 两条通道,都是授权码换 token 再取 userinfo,PKCE 带 code_verifier;回调地址由 request_base_url 从配置推导,不能写死域名,否则反代后回调会落到内网地址。威胁地图按窗口(1h / 3h / 1d / 3d / 7d / all)聚合日志并做短时缓存。

面试速答

  • 组与 Pod:一组一 Pod(namespace clouds),groups.json 是权威状态,K3s 只承载运行态,集群清空也能重建。
  • 资源:limits 用用户上限,requests 用 EWMA 估算且只在 Pod 重建时计算;hostPath 不计入 ephemeral-storage。
  • 网络:frpc 隧道 + 本机 nginx,配置由代码生成、标记块整块重写;子域名五道校验里端口黑名单最容易漏。
  • GPU 与治理:NVIDIA_VISIBLE_DEVICES 管可见性,MPS 百分比管算力;压力驱逐带滞回,读不到压力信号就不动作。
  • 幂等:钱包转账靠共享 token 唯一约束,支付回调靠 out_trade_no 查重;计费每键独立舍入再加总。
  • AI 与安全:工具调用按调用者权限判定,RAG 权限过滤放在召回阶段,IDE Agent 的读写限制在组 home 内。

→ 下一篇:iWiki:协作、检索与开放