导航站是最经典的「自建服务入门项目」，但大部分开源方案要么是纯静态页（改个链接要改代码重新构建），要么后端跑在需要买服务器的地方。

SunNav 把这两头都解决在 Cloudflare 免费套餐里：前端 React + Tailwind 跑 Cloudflare Pages，数据存 D1（SQLite），动态接口用 Pages Functions——没有服务器、没有月费，改链接在后台点一下就行。

• 项目地址：https://github.com/love-ztm/SunNav
• 开源协议：MIT（基于 ModernNav 二次开发）
• 技术栈：React 18 · Tailwind CSS · Vite / Cloudflare Pages Functions · D1

它的辨识度在颜值上：粉色玻璃拟态——毛玻璃卡片、主题色自动取色、背景模糊参数全部后台可调，亮暗双主题还支持各自独立的壁纸。功能上除了常规的分类/链接管理，比较有特色的是聚合搜索命令面板（/ 键唤起，带拼音首字母匹配）、私密分类（访问码登录才可见）和 WebDAV 双目标定时云备份（坚果云 / InfiniCLOUD / AList 都能用，备份列表可查、任意一份一键恢复）。

功能一览

前台

• 三级结构：分类 → 子分组 → 链接，玻璃拟态卡片展示
• 聚合搜索：站内 / Google / Bing 等引擎可配置，/ 快捷键唤起命令面板（支持拼音首字母模糊匹配）
• 三态主题：亮色 / 暗色 / 跟随系统（默认亮色），暗色模式可单独设壁纸
• 外观全可调：每日壁纸、主题色自动取色、背景模糊、卡片毛玻璃参数、卡片宽高 / 图标大小 / 每行卡片数
• 私密分类：访问码登录可见，访客不可见
• 中英双语：未设置时默认中文
• 无闪烁：首屏主题预渲染，刷新和新浏览器打开都不会黑屏
• PWA：可添加到主屏幕

后台（/admin，默认访问码 admin）

• 内容管理：分类/链接增删改、拖拽排序、⭐ 一键指定「打开站点默认显示的分类」
• 外观设置：壁纸、主题色、玻璃质感、布局全参数
• WebDAV 云备份：同时配置两个网盘、定时自动备份 + 保留份数自动清理、备份列表随时查、任意一份一键恢复
• 数据导入导出（JSON）、浏览器书签导入
• 访问码修改（PBKDF2 哈希存储，改后所有已登录设备全部失效）

部署教程（Cloudflare Pages，四步）

第 1 步：Fork 仓库并连接 Pages

1. 打开 SunNav 仓库，点右上角 Fork 到自己账号
2. Cloudflare Dashboard → Workers 和 Pages → 创建 → Pages → 连接到 Git
3. 选择刚 Fork 的仓库，构建配置：
   • 框架预设：Vite
   • 构建命令：npm run build
   • 输出目录：dist

先直接部署一次（此时还没有数据库，但没关系，下一步补上）。

第 2 步：创建 D1 数据库并建表

1. Dashboard → 存储和数据库 → D1 SQL 数据库 → 创建，名字随意（示例用 sunnav-db），建完记下数据库的名称和区域
2. 进入该数据库 → 控制台（Console），把仓库里的 schema-console.sql 的全部内容粘贴进去执行

为什么要区分两份 SQL？ D1 控制台解析不了带 -- 注释的 SQL，所以仓库提供了一份无注释版 schema-console.sql 专供控制台粘贴用；带注释的 schema.sql 是给 wrangler CLI 用的（npx wrangler d1 execute sunnav-db --local --file=./schema.sql）。别拿错文件。

建表后一共六张表：config（配置与访问码）、categories、subcategories、links（三级内容）、rate_limits（IP 限流），初始会写入默认访问码 admin 和 schema 版本号。

第 3 步：绑定 D1 到 Pages

Pages 项目 → 设置 → 绑定（Bindings） → 添加 D1 数据库绑定：

• 变量名：DB（必须叫这个名字，Functions 代码按 env.DB 取）
• 数据库：选第 2 步创建的 sunnav-db

保存后重新部署一次，绑定才会生效。

第 4 步：登录并改密码

1. 访问你的 https://<项目名>.pages.dev
2. 点右下角齿轮图标进入后台（或直接访问 /admin）
3. 登录页只需输入访问码：默认 admin
4. 登录后第一件事：全局设置 → 底部修改访问码

改访问码不是改个字符串那么简单：它以 PBKDF2 哈希存储，且修改会轮换 JWT 签名密钥——所有已登录设备（包括你自己）都会失效，需要重新登录。这是安全设计，不是 bug。

到这一步部署完成，一个 pages.dev 域名、免费 HTTPS、全球 CDN 的导航站就上线了。想绑自定义域名：Pages 项目 → 自定义域 → 按 CF 提示加 CNAME 即可（域名托管在 CF 账号下会自动配）。

WebDAV 定时备份说明

这是 SunNav 最有实用价值的功能，配置前先理解它的工作机制，不然会觉得「怎么没准点备份」。

懒触发机制

Cloudflare Pages Functions 没有常驻定时器（不像 Workers 有 Cron Triggers），所以定时备份采用懒触发：页面打开时（以及打开期间每 10 分钟）静默检查一次，发现「已过设定时间且当天还没备份」就自动执行。

推论：

• 实际备份时刻 = 设定时间之后第一次打开站点。比如设了每天凌晨 3 点，但你 8 点才第一次打开，那备份发生在 8 点
• 页面保持打开就会准点备份（每 10 分钟的自检兜住）
• 就算你从来不打开页面，只要哪天打开了，漏掉的备份会自动补上

配置步骤

后台 → 数据 → WebDAV 备份：

1. 填 WebDAV 地址（必须公网可达——局域网 NAS 地址 Cloudflare 的服务器访问不到）、账号、密码、远程目录
2. 可添加第二个目标（双保险：比如坚果云 + AList 各一份）
3. 设定每日备份时间与保留份数（超出自动清理最旧的）
4. 点保存后可用「立即备份」测试一次，备份列表里能看到每份备份的时间与状态

三条实践建议

• 用应用密码：坚果云走「账户信息 → 安全选项 → 生成应用密码」，别用主密码
• 备份内容：JSON 格式（分类 + 壁纸 + 偏好），与「下载备份文件」的导出格式一致——也就是说手动导出的 JSON 也能直接恢复
• 恢复：备份列表里任意一份一键恢复，覆盖当前站点内容。改了大版本内容前，先手动备份一份

本地开发

1
2
3
4
5

npm install
npx wrangler d1 execute sunnav-db --local --file=./schema.sql   # 本地 D1 建表
npm run dev            # 纯前端开发（Vite，5173 端口）
npm run build          # 生产构建
npx wrangler pages dev ./dist   # 本地全栈模拟（Functions + D1 都在）

想改代码再提交，仓库自带完整质量链：npm run verify 一次跑完 ESLint + TypeScript 双 tsconfig 检查 + Vitest + 生产构建。CI 里也有相同的检查（GitHub Actions）。

常见问题

部署后打开白屏或报 500？

九成是第 3 步没做或没重新部署——D1 绑定是在保存后需要重新部署才生效的。确认绑定变量名是 DB（不是 sunnav-db）。

建表 SQL 执行报错？

用的是带 -- 注释的 schema.sql。控制台请用无注释的 schema-console.sql。

后台进不去 / 密码忘了？

默认访问码是 admin。改过但忘了的话，在 D1 控制台执行 DELETE FROM config WHERE key = 'auth_code' 清掉旧码，系统会回退到默认 admin（此操作会删掉配置表中该键，重新登录后再改新码）。

私密分类访客能看到吗？

看不到。私密分类要访问码登录后才可见，访客的首页完全不渲染它——不是「点了才提示密码」，是彻底不出现。

WebDAV 一直失败？

按顺序查：地址是否公网可达（NAS 内网地址不行）→ 是否用了应用密码 → 远程目录是否存在（程序会自动 MKCOL 创建，405/301 属正常中间态）→ 网盘服务商是否限流。

数据在哪、会不会丢？

全部在 D1 数据库里（Cloudflare 托管，免费版每天 10 万次写远超导航站用量）。但要防误操作/误删，WebDAV 备份就是为此准备的——配好双目标定时备份，等于多了两份异地快照。

小结

SunNav 是那种「架构选型很聪明」的项目：导航站这种低写入、低流量、个人用的服务，放在 Cloudflare Pages + D1 上是零成本的最优解；而 Pages Functions 没有定时器的短板，用懒触发 + 前端周期自检绕了过去，WebDAV 双目标 + 保留策略又把数据安全补齐。加上玻璃拟态的颜值和 PWA、命令面板这些体验细节，作为个人起始页已经相当完整。

部署一句话总结：Fork 连 Pages → D1 建表（无注释版 SQL）→ 绑 DB 重新部署 → admin 登录改密 → 配上双 WebDAV 备份收工。

参考资料

• SunNav 项目仓库（GitHub）
• ModernNav（上游原项目）
• schema-console.sql（D1 控制台专用建表）
• Cloudflare Pages Functions 文档
• Cloudflare D1 文档
• Cloudflare Pages 构建配置

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

域名一多，解析记录就散了：主站在阿里云、CDN 在 Cloudflare、小域名扔在 DNSPod、还有几个在华为云和 NameSilo。每次改个解析要登录四五个后台，密码各不相同，谁到期了也记不清。

HiDNS 就是解决这个的：一个自托管面板，把 26 家 DNS 服务商的解析记录聚合到一起管理，再附带 WHOIS 查询、域名续期调度、NS 监控故障转移这些「顺手的运维能力」。

• 项目地址：https://github.com/HiPM-Tech/HiDNS
• 开源协议：GPL-3.0
• 技术栈：React 19 + Vite 8 前端 / Node.js + TypeScript + Express 后端 / SQLite（默认）、MySQL、PostgreSQL 三选一
• 官方文档站：https://hipm-tech.github.io/HiDNS/

功能特性

多服务商聚合（核心卖点）

一个面板管理 26 家 DNS 服务商的解析记录，A、AAAA、CNAME、MX、TXT、SRV、CAA 等全类型记录增删改查：

创建服务商账号时支持 lego 风格别名（如 alidns → aliyun、edgeone → tencenteo），前端表单由配置字段定义驱动，加新服务商不用改前端代码。

高级能力（超出「聚合」的部分）

架构速览

部署前花一分钟看懂结构，后面排障不慌：

1
2
3
4
5
6
7
8
9
10
11
12

React 19 SPA（client/）
        │
Express API（server/，端口 3001）
        │
统一数据访问层（四层架构）
BAL 业务适配器 → DAL 抽象层 → DL 驱动层 → 数据库
        ＋
DSM 声明式 Schema 管理（自动同步表结构 / 数据迁移）
        ＋
DNS 服务商适配器层（lib/dns/providers/，26 家各一个适配器）
        ＋
后台任务（WHOIS 调度 / 续期调度 / NS 监控 / 服务监控）

亮点是数据库四层架构：所有 SQL 必须经过业务适配器层（BAL），底层驱动可换——这就是它能同时支持 SQLite / MySQL / PostgreSQL 的原因。DSM 层会自动检测并同步表结构差异，升级版本不需要手动跑迁移脚本。

部署路线 A：Docker Compose（推荐）

最省事的方式，一个文件拉起来。

1. 下载编排文件并启动

1
2

curl -O https://raw.githubusercontent.com/HiPM-Tech/HiDNS/main/docker-compose.yml
docker-compose up -d

默认编排用的是官方预构建镜像 ghcr.io/hipm-tech/hidns:latest，一体化模式（前后端合并在一个容器），端口 3001，数据卷挂载 ./data:/app/data。

内置了健康检查（/api/init/status 接口），容器状态直接反映服务是否就绪，配合 restart: unless-stopped 开机自启。

2. 访问并初始化

浏览器打开：

1

http://服务器IP:3001

首次启动会跳转初始化向导：http://localhost:3001/setup。在向导里配置数据库并创建第一个管理员账号。

安全设计说明：HiDNS 没有固定默认账号（不存在 admin/admin123 这种），管理员只能通过初始化向导或 /api/init/admin 接口创建。且系统初始化完成后，/api/init/database 会返回 403 拒绝再次初始化——不用担心别人趁虚而入重置你的系统。

3. 验证

• 面板能登录
• http://服务器IP:3001/api/docs 能打开 Swagger 文档
• docker logs hidns 无报错

部署路线 B：docker run 一条命令

不想用编排文件的话：

1
2
3
4
5

docker run -d \
  -p 3001:3001 \
  -v $(pwd)/data:/app/data \
  --name hidns \
  ghcr.io/hipm-tech/hidns:latest

效果完全一致（数据卷是关键，/app/data 里存着数据库和配置）。

部署路线 C：源码运行（开发 / 想看代码）

环境要求：Node.js ≥ 18 + pnpm（注意：技术栈标注后端依赖 Node 24 的内置 node:sqlite，用 SQLite 模式建议直接上 Node 24，避免 node:sqlite 不可用）。

1
2
3
4
5
6
7
8
9
10

pnpm install

# 开发模式：同时启动后端（3001）与前端（5173）
pnpm dev
# 访问 http://localhost:5173

# 聚合模式（单端口，与 Docker 行为一致）：
pnpm --filter client build     # 先构建前端
cd server && pnpm dev          # 后端同时提供 API 和静态页面
# 访问 http://localhost:3001

想自己构建镜像：

1
2

docker build -t hidns .
docker run -d -p 3001:3001 -v $(pwd)/data:/app/data --name hidns hidns

数据库选择：SQLite 够用，MySQL/PG 可切换

默认 SQLite（单文件，就在 ./data 里），个人和小团队完全够用。数据量大或要多实例共享时切 MySQL / PostgreSQL。

docker-compose.yml 里已经预置了注释好的 MySQL 和 PostgreSQL 服务段，取消注释即可：

• MySQL 8.0：mysql-data 卷 + hidns 库 + 自定义密码
• PostgreSQL 15：postgres-data 卷 + hidns 库

同时在环境变量里把 DB_TYPE 从 sqlite 改成 mysql 或 postgresql，并填上 DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD。

切库时机建议：第一次初始化之前就定好。初始化向导里也要选一致的库类型，避免「compose 里起了 MySQL、向导里还在用 SQLite」的乌龙。

环境变量详解

HiDNS 的配置文件是 data/.env（自动加载，优先级最高）或项目根目录 .env——从 .env.example 复制一份开始改：

JWT 双层密钥机制值得单独说：实际签名密钥 = JWT_SECRET + 一个存在数据库 runtime_secrets 表里的运行时密钥。首次初始化创建管理员后会主动轮换一次——这也是为什么没设 JWT_SECRET 的话，容器一重启全员被踢：运行时密钥是随机生成的。

使用说明

第一步：接入 DNS 服务商账号

面板里添加服务商账号，填对应平台的 API 凭证（如阿里云的 AccessKey、Cloudflare 的 API Token）。26 家都在列表里，凭证只存在你自己的数据库里。

第二步：统一管理解析记录

选择域名后即可对 A、AAAA、CNAME、MX、TXT、SRV、CAA 等全部类型做增删改查，操作会由对应服务商的适配器转发到上游。

Cloudflare 专属字段要注意：Cloudflare 的「代理开关（小黄云）」不在通用 line 字段里，而是用请求/响应中的 cloudflare.proxied（true = 代理，false = 仅 DNS）与 cloudflare.proxiable（当前类型是否支持代理）字段；不传 cloudflare.proxied 时才回退到 line（'1' 代理 / '0' 仅 DNS）。

第三步：运维自动化

• WHOIS 与续期：录入域名后自动查询 WHOIS（带缓存），续期调度器按到期时间提前提醒/调度
• NS 监控：定时探测 NS 记录，异常时触发故障转移任务
• API Token：在面板里签发细粒度权限的 Token，给 DDNS 脚本、自动化工具调用，不用把管理员账号到处贴
• API 文档：/api/docs 的 Swagger 是权威接口文档，写自动化脚本直接照着调

第四步：安全加固（生产必做）

• 面板挂 HTTPS 反代后，设置 COOKIE_SECURE=true（或留空走自动检测）
• 面板登录开启 TOTP 双因素，或配置 OAuth2/OIDC 接你自己的 SSO
• 支持 WebAuthn/Passkeys：记得配好 WEBAUTHN_RP_ID 和 WEBAUTHN_ORIGIN
• 开启 审计日志 审查敏感操作
• 不想暴露公网：放到内网使用，或在反向代理层加访问控制（IP 白名单 / Basic Auth）

常见问题

每次重启容器，所有人都被踢下线？

没设 JWT_SECRET。默认每次重启随机生成密钥，旧 Token 全部失效。生产环境在 data/.env 里设一个 64 位以上随机字符串即可。

初始化向导打不开 / 提示 403？

向导只在未初始化阶段可用。如果数据库里已经有用户，/api/init/database 会返回 403——这是防重置保护。想重来就清空 ./data 目录（会删掉全部数据，先备份）。

面板在 HTTPS 反代后面，登录后 Cookie 异常？

两个变量配合：COOKIE_SECURE=true + TRUST_PROXY（不设会用生产默认的内网信任段；Nginx 不在内网段时显式设 true 或指定网段）。

SQLite 和 MySQL 怎么选？

单机自用、域名几十个以内：SQLite（WAL 模式）足够。多实例、团队并发大、要接现有数据库设施：MySQL / PostgreSQL，compose 里取消注释对应段即可。

界面有英文吗？

没有。官方明确「界面只有简体中文」，i18n 框架已在重构中整体移除——中文用户友好，但别等英文版了。

能接 AI 助手吗？

能。项目内置 MCP Server（Model Context Protocol），可以接支持 MCP 的 AI 客户端来查询和操作 DNS 记录，仓库 docs/MCP_*.md 有实现说明。

小结

HiDNS 这类聚合面板的价值，在于把「N 个服务商后台」收敛成「1 个自己的后台」：解析记录一处改、到期续期有人盯、NS 出事自动切，而且数据全部在自己手里。Docker 一条 docker-compose up -d 就能起，初始化向导零配置文件门槛，SQLite 起步、量大了再切 MySQL——上手成本基本只有「填一遍各家的 API 凭证」。

域名超过十个还没用聚合面板的话，值得花半小时部署一个。

参考资料

• HiDNS 项目仓库（GitHub）
• HiDNS 官方文档站
• Docker 镜像（ghcr.io）
• HiDNS API 文档（部署后 /api/docs）
• WebAuthn / Passkeys 说明

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

做「给别人提供服务」的东西，迟早会撞上一个问题：客户想用自己的域名接入，但客户的域名不在你的 Cloudflare 账号里。

传统做法是让客户把域名 NS 迁过来——不现实。正确姿势是 Cloudflare 官方的 Cloudflare for SaaS：你提供入口，客户只加一条 CNAME 指向你，证书由 Custom Hostname 自动签发。

cf-saas-tenant-router 就是把这套能力做成了开箱即用的多租户系统：

• 项目地址：https://github.com/lzmss-love/cf-saas-tenant-router
• 技术栈：Cloudflare Workers + D1（三张表）+ Custom Hostnames + GitHub Actions
• 定位：客户域名不托管 CF，加一条 CNAME 即可把流量接入你的 Worker，按 Host 分流转发到各自的上游（tgproxy / cf-erp / cf-subcloud 等均可）

整条链路：

1
2
3
4
5
6
7
8
9

客户域名（NS 留在客户自己的 DNS）
        │ CNAME → opt.<宿主域名>（优选 IP，灰云 A 记录）
        ▼
Cloudflare 边缘 ── Custom Hostname（证书自动签发）── */* route
        ▼
saas-tenant-router Worker
   ├─ 按 Host 查 D1 租户表 → 转发上游
   ├─ Origin 改写 + 页面域名替换 + WebSocket 透传
   └─ bridge cap 重算（客户手里任何域名版本的接入凭证都能过认证）

部署完成后你会得到：

功能特性

管理面板（四个标签页）

几个设计细节（源码确认）

• 接入码防呆：8 位随机码，字符表去掉了 0 O 1 I L 这类易混淆字符，口头报给客户也不会念错
• 租户状态机：pending（没配上游，仅标记）/ active（配了 upstream，正常转发）/ suspended（管理员停用，立即停止转发）/ 软删除
• 上游两级配置：租户表里每行可配 upstream_base（租户专属），没配则回落到全局变量 TENANT_UPSTREAM_BASE；两者都没有时返回提示页，而不是报 1016
• 面板与 API 只认宿主域名：管理接口只在宿主 zone（及可选的 workers.dev 后缀）上响应，且需要 ADMIN_TOKEN（格式 账号:密码），客户域名上根本访问不到
• 兼容严格上游：对 tgproxy 这类做 bridge 校验的服务，Worker 会按上游真实 hostname 重算 cap——客户手里任何域名版本的接入凭证都能过认证

部署前准备（人工三件套，无法 API 化）

无论用哪种部署方式，每个 Cloudflare 账号都要先手工完成这三步：

1. 宿主域名加入该 CF 账号（NS 托管，Free 计划即可）
2. Enable Cloudflare for SaaS：控制台 → SSL/TLS → Custom Hostnames → Enable（需要绑卡——这是 CF 唯一不给 API 的步骤）
3. Fallback Origin：同一页面 → Fallback Origin 栏填 service.<你的域名> → 等 Active。注意这一步只能控制台点，API 会报 10405（CF 硬限制）

然后建一个 API Token（控制台 → My Profile → API Tokens）。CLOUDFLARE_API_TOKEN 一共需要 11 项权限，建 Token 时对着下面的清单逐项勾选即可（级别列标注了它挂在「账户」还是「区域」下）：

Zone Resources 只选你的宿主 zone（账户级的 D1 / Workers Scripts 权限跟随账户，区域级权限锁定该 zone），最小权限。

部署路线 A：本机一条命令初始化（推荐）

仓库是模板化的：拿到任何新 CF 账号，域名/账号/D1 全部自动配置，代码零修改。

1
2
3
4
5
6
7
8
9

# 1) clone 到一个新目录（重要：不要在已有部署的目录里跑）
git clone https://github.com/lzmss-love/cf-saas-tenant-router.git my-new-saas
cd my-new-saas && npm i

# 2) 一键初始化（Git Bash 语法）
CF_API_TOKEN=xxx node scripts/init.mjs <你的宿主域名>

# PowerShell 写法：
#   $env:CF_API_TOKEN="xxx"; node scripts/init.mjs <你的宿主域名>

init.mjs 会自动完成：查 zone id → 建 D1 → 重写本目录的 wrangler.jsonc（routes / D1 / vars 全部指向新账号）→ 建 DNS 记录（fallback origin / customers / opt）→ 打印剩余的手动步骤。

然后收尾两件事：

1
2

npx wrangler deploy          # 部署 Worker + 路由
npm run optimize             # 跑一次优选，把最快的 IP 写进 opt 记录

⚠️ init.mjs 会重写当前目录的 wrangler.jsonc。在 clone 出来的新目录里跑，不要在已有部署的目录执行，否则当前账号的配置会被覆盖。

部署路线 B：手动部署（想搞懂每一步）

1
2
3
4
5

npm i
npx wrangler d1 create saas-tenants
# 把输出的 database_id 填进 wrangler.jsonc（从 wrangler.template.jsonc 复制一份开始改）
npx wrangler d1 migrations apply saas-tenants --remote
npx wrangler deploy

三个 secret（存 CF 侧）

1
2
3

npx wrangler secret put ADMIN_TOKEN        # 面板登录，格式 账号:密码
npx wrangler secret put CF_API_TOKEN       # DNS / Custom Hostnames 操作
npx wrangler secret put TGPROXY_SECRET     # tgproxy 的 SECRET，用于 bridge cap 重算（不接 TG 可不配）

关键纪律：一切凭证走 secret，不要在 Dashboard 建 plain text 变量——wrangler deploy 会用 wrangler.jsonc 的 vars 段整体替换明文变量，Dashboard 里建的会被清掉。secret 不受影响。

wrangler.jsonc 的 vars 段（配置全在这）

配置全部在 vars 里，代码零硬编码。改完 npx wrangler deploy 生效。

验证

1
2

curl https://<宿主域名>/health
# {"ok":true,...}

浏览器打开 https://<宿主域名>，能用 ADMIN_TOKEN 登录面板即部署成功。

部署路线 C：GitHub Actions 全自动（push 即上线）

仓库自带 .github/workflows/deploy.yml，push 到 master（或手动触发）自动完成全流程：

1
2

查 zone id → 建/找 D1 → 渲染配置 → 部署 Worker → D1 迁移
→ 自动写入运行时密钥 → 幂等补齐 DNS 基础记录

一次性配置

1. 建部署专用 API Token：权限与上文「部署前准备」的 11 项清单完全一致（D1 / Workers Scripts / DNS / SSL and Certificates / Workers Routes 的读写 + Zone Read），Zone Resources 选宿主 zone
2. GitHub 仓库 → Settings → Secrets and variables → Actions，配这些 repository secret：

zone id / D1 id / CNAME target 都不用填——Actions 自动解析，D1 不存在会自动创建。

单仓库管多个 CF 账号（Environments）

这是这套 CI 的亮点：每个账号一个 GitHub Environment，手动触发时 target 自由输入账号名：

1. Settings → Environments → New environment，名称填账号名（如 maowei）
2. 在该 environment 的 Secrets 里配置该账号的一套 secrets
3. Actions → Deploy → Run workflow → target 填 maowei → 部署到对应 CF 账号

指定 target 时，zone/D1 会按 zone 名在目标账号实时解析（忽略仓库级回退 ID，避免跨账号错绑路由）。新增账号不需要改任何代码；push 自动部署不受影响（无 target = 仓库级 secrets = 主账号）。

使用说明

新客户接入流程（约 3 分钟）

1. 面板「接入码」→ 生成 → 发给客户（复制按钮自带接入地址）

2. 客户打开 https://<宿主域名>/join → 输接入码 + 自己的域名 → 页面直接给出要加的 CNAME：

   1	<客户域名> CNAME opt.<宿主域名>

3. 客户在他的 DNS 服务商添加这条记录。注意两点：不能用 A 记录；apex 根域名不支持——让客户用子域（如 app.客户域名）

4. 面板「自定义主机名」→ 为该 host 创建 Custom Hostname → 点详情，把弹窗里的 DNS 指令发给客户补加（验证 TXT 或 DCV 委派 CNAME，按客户情况二选一）

5. 等证书与主机名两个状态都变绿。如果证书一直「待验证」：查客户域名的 CAA 记录（会沿 DNS 树向上继承），需要授权签发 CA，例如加 0 issue "ssl.com"，或删除现有 CAA

完事之后 Worker 已经自动识别新租户，流量按其 upstream_base 转发。

日常管理

• 停用某个客户：租户页 → 停用（状态变 suspended，立即停止转发，且不影响其 Custom Hostname 证书）

• 给某客户换上游：编辑该租户的 upstream_base，立即生效，无需重新部署

• 查某个客户为什么打不开：D1 里有 req_log 请求日志（method / path / query / UA / IP / status），直接看客户端的真实请求形态：

  1 2	npx wrangler d1 execute saas-tenants --remote \ --command "SELECT * FROM req_log ORDER BY id DESC LIMIT 20"

• 面板按钮没反应：面板是单文件 HTML 内嵌 JS，先跑 node scripts/check-embedded-js.mjs 做语法检查再部署

优选 IP 维护

优选解决的是「国内访问 CF 边缘入口慢」：客户域名解析到测速优选的 CF IP，SNI 路由不变。

1

CF_API_TOKEN=xxx npm run optimize

• 对 24 个候选 IP 测 TLS 握手 → 自动把最快的写入优选记录（IP 没变则跳过写入）
• 换 IP 只改 DNS 记录，客户域名不用动，代码不用动
• 优选入口支持两种形态：A 记录（直指优选 IP）或 CNAME（指社区优选域名如 *.cf.090227.xyz，自动更新更省心）；面板更新时保持原类型
• 建议每周跑一次；如果某天客户集体打不开（IP 失效），立即跑一次
• 非标端口的反代节点（如 IP:26524）对 TG WEB 类客户端无用（固定 443 且无端口字段），仅适合支持自定义端口的客户端

面板「优选」标签页也可以直接做多路管理（opt / opt2 / opt3… 增删改、切换 A/CNAME、在线测速），不用碰命令行。

常见问题速查

安全注意事项

• ADMIN_TOKEN 用随机长串，它是面板与管理 API 的唯一门禁；管理接口本身也只在宿主域名上暴露
• CF_API_TOKEN 最小权限：Zone Resources 锁定宿主 zone，别用 Global API Key
• 凭证一律走 secret，不要写进 wrangler.jsonc 明文 vars（会被 push 和部署清掉，还可能随模板仓库泄漏）
• 客户接入码一次性 + 可作废，泄露了直接在面板作废重新生成
• req_log 是诊断表，会记录客户请求的 path 与 UA——自己留档没问题，对外分享日志时注意脱敏

小结

这套项目把「Cloudflare for SaaS 多租户」这件事从一堆控制台操作变成了三条可重复的路：本机 init 一键初始化、手动部署搞懂原理、Actions push 即上线，再配上接入码自助接入、面板化租户管理、自动优选 IP。适合的场景很明确：你要给多个客户/多个域名提供同一种入口服务（代理入口、自建应用、API 网关都行），又不想让客户迁移域名托管。

部署口径总结成一行：宿主域名托管 + Enable for SaaS + Fallback Origin 三件套 → init 或 Actions → 发接入码 → 客户加一条 CNAME → 建 Custom Hostname → 双绿灯收工。

参考资料

• cf-saas-tenant-router 项目仓库（GitHub）
• Cloudflare for SaaS 文档（Custom Hostnames）
• Cloudflare Workers D1 文档
• Wrangler CLI 文档
• Cloudflare API Token 权限说明
• GitHub Actions：Environments 使用

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

cftgwebproxy 是一个开源的 Telegram Web Proxy 部署方案：用 Cloudflare 的免费资源把 TG 的 MTProto 代理跑起来，客户端填一个自己的域名就能连。

• 项目地址：https://github.com/xinyitang3/cftgwebproxy
• 开源协议：MIT
• 技术栈：Cloudflare Pages（主程序）+ Workers（转发层、DNS 定时任务）+ Cloudflare DNS API
• 上游：协议逻辑来自 ToiCF/CF-Workers-TGProxy

它和我之前写过的单文件 Worker 代理方案不太一样，最大的特点是拆成三层：

为什么要这么拆？项目 README 给了两个理由，都挺实在：

1. 避开 1101 / 522：Worker 直接长时间挂着 WebSocket 代理，容易触发 Worker 异常（1101）和源站超时（522），把主程序放 Pages 能显著降低这类报错；
2. 额度分开算：按作者的说法，Pages 和 Worker 的请求额度是分开计算的，拆开后总容量更大。

最终链路是这样：

1
2
3
4
5

Telegram 客户端
   → 你的优选域名（A 记录由 Cron 自动更新）
   → Worker 转发层（webproxy-relay.js）
   → Pages 主程序（telegram_webproxy.js）
   → Telegram 服务器（KWS / DC）

本文依据仓库 README 与三个脚本的源码整理，环境变量规则、接口路径、校验逻辑均以源码为准。部署时请以仓库最新提交为准。

准备工作

开干之前，把这几样东西备齐：

先生成两个密钥，后面两个组件都要用：

1
2
3
4
5

# BOOT：建议 ≥16 位随机字符串
openssl rand -hex 24

# SECRET：32 位小写十六进制（openssl rand -hex 16 刚好 32 个字符）
openssl rand -hex 16

环境变量的两条硬规则（源码里写死的校验，填错直接 500）：

• SECRET：必须是 32 位小写十六进制（0-9a-f），或者 dd + 32 位十六进制（共 34 位）
• BOOT：任意非空随机字符串，建议 16 位以上

关于 dd 前缀：它是 MTProxy 的可选模式，作用是启用随机填充（Random Padding），把包长随机化。填的时候必须带上 dd 两个字面字符，共 34 位；不带前缀就是标准的 32 位 secret。客户端里要填和这里完全一致的字符串。

第一步：部署 Pages 主程序

这一层是整个方案的核心。

1.1 新建 Pages 项目

Cloudflare 控制台 → Workers 和 Pages → 创建 → Pages → 上传资产（直接上传，最省事）。

1.2 文件必须改名成 _worker.js

这是最容易踩的坑：把 telegram_webproxy.js 重命名为 _worker.js，放在上传目录的根目录。

原因：Pages 的 Functions 高级模式只认根目录下这个固定文件名，名字不对就完全不会执行你的代码，页面只会返回静态 404 或空白页。

1
2

上传目录/
└── _worker.js     ← telegram_webproxy.js 改名而来，必须在根目录

1.3 配置两个加密变量

项目 → 设置 → 变量和机密（Environment variables），两个都建议用**加密（Secret）**方式添加：

保存后重新部署一次，让变量生效。

1.4 验证主程序

部署完成后访问：

1

https://<项目名>.pages.dev/health

返回下面这行就说明主程序活了：

1

{"ok":true}

如果这里就是 500，别急着往下做——先回去检查 BOOT / SECRET 的格式（最常见就是 SECRET 长度不对或包含大写字母）。

1.5 主程序到底做了什么（看懂再调）

顺手把源码里的关键设计说一下，排障时很有用：

• 对外接口只有四个：/（桥接页）、/health、/api/v1/session、/api/v1/ws，其他路径一律 404
• /api/v1/session：用 BOOT 派生的 Bearer 令牌做鉴权，POST 一段二进制握手数据，成功后通过响应头 X-Session-Token 返回会话令牌
• /api/v1/ws：真正的数据通道，要求 Upgrade: websocket，且子协议必须形如 tproxy-lane-v1.<令牌>.<通道号>；Origin 若不等于自身 Origin 会被拒绝
• 帧协议：8 字节帧头（类型 + 会话 ID + 长度），单帧上限 1 MB，单条消息最多 4096 帧；每个令牌最多 128 条并发通道、累计 4096 个通道号
• 安全头：返回的桥接页带 sandbox 的 CSP，且 frame-ancestors 只允许 http://127.0.0.1:*——这是给 Telegram Desktop 的本地页面做嵌入用的

所以：直接用浏览器打开 https://你的域名/ 看到一个几乎空白的 “Connection” 页是正常的。 那个页面的完整版只有在带上正确签名的 ?bridge= 参数时才会渲染，而签名由转发层按 SECRET 计算，客户端会通过本地页自动完成——不需要你手动拼。

第二步：部署 Worker 转发层

这一层的唯一任务是：把你的域名请求原样转给 Pages 主程序，并把返回内容里的地址改写回你的域名。

2.1 新建 Worker

切换到第二个 Cloudflare 账号（如果你按建议分了两个），Workers 和 Pages → 创建 Worker，把 webproxy-relay.js 的内容整体粘贴进去，部署。

2.2 配置变量

HOST 填错的典型症状是：域名访问全 404 或 502。代码里会自动剥掉协议头和端口，但填自定义域名仍然会错——它要求的是 *.pages.dev 那个原始域名。

2.3 绑定路由

Worker → 设置 → 域和路由 → 添加路由，把你的优选域名挂上去：

1
2

你的域名/*          ← 对应根域名 @
*.你的域名/*        ← 对应任意子域名

两条都加，覆盖面最全。注意：该域名的 Zone 必须和这个 Worker 在同一账号，否则界面根本不会让你选这个 Zone，这是 Cloudflare 的限制，不是项目的问题。

2.4 验证转发

1
2

curl https://你的域名/health
# 期望：{"ok":true}

能通说明「域名 → Worker → Pages」这条链已经打通了。

2.5 转发层做的三件细活

源码里有几个处理值得知道，出问题时能对上号：

1. 重签桥接令牌：客户端带的 ?bridge= 是按「当前域名」用 HMAC-SHA256 算的，转发层会校验并在转发时改写成按 pages.dev 域名计算的版本，这样桥接页在自定义域名下也能正常渲染；
2. 改写回跳地址：遇到 3xx 重定向，把 Location 里的 pages.dev 换回你的域名；
3. 改写 HTML：对 text/html 响应做字符串替换，把 https://页域名 与 wss://页域名 全部换回你的域名，同时清掉 Content-Length、Content-Encoding、ETag 等会因为改写而失效的头。

它还严格校验 WebSocket 的 Origin：只有等于 https://你的域名 才放行，否则直接 404。所以用其他域名或裸 IP 去连是连不上的，这是设计如此。

第三步：让优选 IP 自动更新（可选但强烈推荐）

Cloudflare 的 Anycast 会让你落到就近节点，但不同 IP 段在你的网络环境下质量差很多。这一层用 Cron 定时把「测得快的 IP」写进 A 记录，避免手动维护。

3.1 建一个有 DNS 编辑权限的 Token

Cloudflare 控制台 → 我的个人资料 → API 令牌 → 创建令牌，模板选「编辑区域 DNS」：

• 权限：Zone → DNS → Edit
• 区域资源：只选你的优选域名这一个 Zone（最小权限）
• 创建后把令牌复制保存

顺手记下这个 Zone 的 Zone ID（域名概览页右下角）。

3.2 新建 Worker 并改三个常量

再建一个 Worker，粘贴 domain-dns.js，改开头这几个常量：

1
2
3
4
5
6
7
8
9
10
11

// 优选 IP 源：返回文本，每行 IP:Port，可带 # 注释
const URL = 'https://你的IP源地址';

// 你的优选域名
const DOMAIN = 'example.com';

// 会分别同步 @ 根域名 和 * 通配子域名
const RECORD_NAMES = [
  { label: '@', fqdn: DOMAIN },
  { label: '*', fqdn: `*.${DOMAIN}` }
];

3.3 配置变量与 Cron

然后在 Worker → 触发器 → Cron 触发器 里加一条，例如每 30 分钟：

1

*/30 * * * *

免费计划同样支持 Cron 触发器，但每次触发都会计入请求次数，别设得过于频繁（比如每分钟一次完全没必要，优选 IP 的变动频率远低于此）。

3.4 这层脚本的逻辑（便于自查）

• 拉取 IP 源文本，只保留端口为 443 的条目（其他端口直接忽略）
• 对 @ 和 * 两条记录：分页读出当前所有 A 记录 → 删掉不在目标列表里的 → 补上缺的
• 新记录 TTL 设为 60 秒，改动后一分钟内全网生效
• 会容忍 Cloudflare 的「记录已存在 / 内容重复」类错误码，不会因为并发重复创建而整体失败

3.5 验证

1. Worker 的 日志 里能看到每次 Cron 的执行结果（同步了哪些 IP、有没有报错）
2. 本地查一下记录：

1

nslookup 你的域名 1.1.1.1

返回的 IP 应该和你的优选 IP 源里 443 那批对得上。

第四步：客户端配置

到这一步，服务端已经就绪。客户端只需要三个字段：

Telegram Desktop（Windows / macOS / Linux）

设置 → 高级 → 连接类型 → 代理 → 添加代理 → 类型选 MTProto → 填入上面三项 → 保存 → 选中该代理。

Telegram Android / iOS

设置 → 数据和存储 → 代理（部分版本在「聊天设置 → 代理」）→ 添加代理 → MTProto → 填入三项 → 启用。

判断是否真的连上了

• 客户端代理列表里该条目显示已连接 / Connected
• 打开任意频道能正常收发消息
• 服务端侧可以访问 https://你的域名/health 确认主程序存活

如果客户端一直转圈：先确认 https://你的域名/health 返回 {"ok":true}，再检查客户端里的 secret 有没有少一位或多一位（尤其 dd 前缀很容易漏）。

额度与性能

几个实测向的优化建议：

• 优选 IP 源的质量决定了 90% 的体验。换几个源对比延迟再定，别用来源不明的列表
• Cron 频率 30–60 分钟足够，IP 失效通常不会在几分钟内发生
• 如果你只是自己用，只加 @ 根域名那条记录也行，少一条记录少一次 API 调用
• 出现 1101 / 522 时，优先检查是不是有人在猛拉流量，或 Workers 侧并发太高；主程序留在 Pages 是这套方案的核心思路，不要改动

常见故障排查

/health 返回 500

BOOT 或 SECRET 缺失、格式不对。重点查 SECRET：必须 32 位小写十六进制，或 dd + 32 位；有大写字母、长度 31/33 都会失败。

访问域名全部 404

三种可能，按顺序排查：

1. Worker 路由没加（或缺 * 通配那条）
2. 域名 Zone 与 Worker 不在同一 Cloudflare 账号
3. HOST 填错了（必须是最原始的 *.pages.dev，不是自定义域名）

页面能开，但 Telegram 一直连不上

• Worker 里 SECRET 与 Pages 里不一致 —— 这是最常见原因
• 客户端 secret 填错（dd 前缀漏填或重复）
• WebSocket 被中间层拦了：转发层要求 Origin 严格等于 https://你的域名

从浏览器打开 https://你的域名/ 是一片空白

正常现象。桥接页需要合法签名的 ?bridge= 参数才会完整渲染，客户端会自动处理，不需要手动拼。

DNS 不自动更新

• API_TOKEN 权限不足（必须含该 Zone 的 DNS Edit）
• ZONE_ID 填错
• Cron 没启用，或最近一次执行报错（看 Worker 日志）
• IP 源返回的条目里没有 :443，脚本会全部过滤掉

偶尔 1101 / 522

1101 是 Worker 运行时抛异常，522 是源站超时。两个都属于「Worker 直接扛代理」的固有问题，这也是本方案把主程序放 Pages 的原因。降低并发、别把域名公开给大量陌生人使用，能明显缓解。

想换 SECRET 怎么办

必须同时改两处（Pages 主程序 + Worker 转发层），改完重新部署，然后通知所有客户端更新 secret。只改一边会导致全部连不上。

安全与注意事项

• SECRET 就是这台上网的钥匙：拿到「域名 + secret」的任何人都在白嫖你的代理，不要发到公开群组或仓库里
• API_TOKEN 只给最小权限：只勾选该 Zone 的 DNS 编辑，别用全局 API Key
• 三个组件建议分账号部署，一处泄露不至于全线崩塌
• 密钥用「机密（Secret）」类型存，不要写死在代码里再上传
• 本项目用于合法的通信与学习用途，请自行遵守所在地法律法规以及相关平台的服务条款

小结

把整套流程压缩成一张清单：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

① Pages：telegram_webproxy.js → 改名 _worker.js → 传根目录
   变量：BOOT（随机串）、SECRET（32 位 hex 或 dd+32 位）
   验证：/health → {"ok":true}

② Worker：webproxy-relay.js
   变量：HOST = xxx.pages.dev、SECRET = 同上
   路由：域名/*、*.域名/*
   验证：curl https://域名/health

③ Worker + Cron：domain-dns.js
   改：URL、DOMAIN
   变量：ZONE_ID、API_TOKEN（DNS Edit）
   Cron：*/30 * * * *（按需）
   验证：nslookup 看 A 记录

④ 客户端：MTProto · 域名 · 443 · SECRET

这套方案最值得学的地方，其实是它「用 Pages 扛长连接、用 Worker 只做转发」的工程取舍——1101/522 这类边缘平台的老问题，靠架构拆分绕过去，比在单文件里加一堆重试优雅得多。想自己搭一套 TG 代理的话，按上面四步走，半小时能跑通。

参考资料

• cftgwebproxy 项目仓库（GitHub）
• 上游协议实现：ToiCF/CF-Workers-TGProxy
• Cloudflare Pages Functions 高级模式（_worker.js）
• Cloudflare Workers 路由配置
• Cloudflare Workers Cron 触发器
• Cloudflare API：DNS 记录管理
• Telegram MTProto 代理说明

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

2026 年 9 月起，GitHub 上一批新项目突然爆发式增长：把腾讯 CodeBuddy / WorkBuddy 的账号包装成 OpenAI 兼容 API，再配上 Web 管理面板做账号池。代表性的是这两个：

两个仓库都是 9 月中旬创建、一个月内涨到数千星，标签里写满了 reverse-proxy、openai-api、account-manager。对想省钱用上大模型 API 的人来说，吸引力很直接：注册个免费账号，扫个码，就能在自己的客户端里用上「兼容 OpenAI 格式」的接口。

但这篇文章不教部署。 我要做的是另一件事：把这两个项目自己在 README 里写下的内容当作证据，逐条算清楚这笔账——省下的钱，和你要押上去的东西相比，到底值不值。

先看它们自己怎么说

这两份 README 的信息量，比任何第三方分析都大。

证据一：主项目已经自己停维护了

workbuddy2api-panel 在 README 顶部用醒目块写明：项目已停止维护（2026-10-21），不再更新代码、不跟进上游变化、不再处理新的 issue/PR。给出的三条原因，值得逐字读：

1. 上游已开始禁用反代——WorkBuddy 对非官方客户端的识别与拦截正在收紧（通道校验、账号限制等），反代通道的稳定性与存续周期已不可控，继续做适配意义有限
2. 一人精力有限——这是一个人的自用工具，无力长期跟进协议变化与风控对抗
3. 非法转售泛滥——发现大量批量注册小号、对外售卖额度、二次加壳 / 卡密分发的滥用行为，与本项目初衷完全相悖

它还明确写了一句：「因使用非官方客户端导致的账号风控 / 封禁，由使用者自行承担。」

这三点等于把这类项目的生命周期判决书写在了脸上：上游在查、作者跑了、生态里全是转卖的人。

证据二：上游仓库已经删除了

同一个 README 里还有一条：本项目是 Sliverkiss/workbuddy2api 的增强分支，而上游仓库现已删除。

一个被上游删除的项目，说明什么？说明平台方的态度已经明确了。你现在照着任何一个 fork 部署，等于在一个已经被官方盯上、原作者已经撤掉的通道上继续跑流量。

证据三：免责声明把灰产路径写全了

workbuddy-manager 的 README 里有这样一段使用边界：

仅可用于管理本人及亲属自愿授权的账号；禁止批量注册、账号交易、代注册、接码、盗号、绕过平台风控，以及任何商业转售或盈利性用途。

需要专门写这么长一串「禁止」，本身就说明了这个生态里实际在发生什么。代注册、接码平台、账号买卖——这些不是边缘现象，是这类工具的主要使用场景之一。

证据四：赞助商是住宅代理，这就是风控对抗的成本

最耐人寻味的一条：workbuddy-manager 的 README 顶部挂着一个住宅代理服务的赞助位，并解释了用法——在代理的用户名里写上国家、城市和会话名，每个实例走一个住宅 IP，最长 72 小时不变，换 IP 也留在同一城市。

为什么一个「账号管理工具」需要给每个账号配一个独立住宅 IP、还要保持城市一致？

答案不言自明：因为同 IP 多账号是最典型的批量行为特征，会被风控识别。这段赞助文案，实际上是一份「规避平台风控的技术需求说明书」。

这也顺手回答了成本问题：想稳定用这套东西，你还要额外买住宅代理（赞助码还打着 7 折）。省下的订阅费，先要扣掉一笔代理费。

五类风险逐条算账

1. 账号风险：封号是设计内的结果，不是意外

这类网关的本质是用非官方客户端模拟官方流量，去访问平台的私有接口。平台的服务条款通常明确禁止：自动化访问、接口逆向、账号出借或共享、批量注册。三类行为叠加在一起，被封不是「运气不好」，而是迟早的事。

更麻烦的是连坐：多数人用的腾讯账号是同一个账号体系，一旦因为这个通道被标记，影响范围可能不止于 CodeBuddy。

2. 凭据风险：扫码纳管等于交出登录态

「扫码纳管」听起来无痛，实际操作是把账号的登录凭证 / 会话令牌交给一个 Web 控制台，由它在后台代表你发请求、签到、保活。

那么问题来了：你把凭证交给了谁？

• 一个 2026 年 9 月创建的仓库
• 一个自述「近期 issue/PR 处理、代码审查、测试与修复实现大量由 AI 辅助完成」的项目
• 一个上游已经被删除、主分支已经停维护的生态

这些描述并不意味着作者有恶意——但审计难度是客观的。代码量不小、AI 代写成分高、更新频繁、还带一键自动更新。任何一处后门或漏洞，代价是别人拿着你的登录态为所欲为。这类凭证往往无法用「改个密码」简单止损，因为会话令牌可能已经长期有效。

3. 供应链风险：签名校验证明不了「作者可信」

workbuddy-manager 强调「带签名校验的一键更新」。这是好设计，但要理解它到底保证了什么：

• 它保证：这次更新确实来自同一个作者，没被中间人篡改
• 它不保证：这个作者是可信的

信任锚点仍然是人。而这个人是匿名 ID、项目一个月新、二进制发布、还会自动更新——这是供应链攻击面里最难审计的一种组合：你运行的是一份没有可复现构建、随时会被替换的二进制。

4. 稳定性风险：协议一改，全部归零

私有接口是逆向出来的，没有任何兼容承诺。平台改一个字段校验、加一层设备指纹、换一次签名算法，你的网关立刻 502。

这件事已经发生了：主项目 10 月 21 日停更，理由第一条就是「上游已开始禁用反代」。你花几小时部署好的东西，可能明天就变成一堆报错的日志——而那时你已经把工作流搭在它上面了。

5. 成本与合规：省的钱可能还没赔的多

把账算全：

在个人娱乐场景，最坏结果是损失一个账号。但如果这被用在任何有交付责任的地方，赔的就不只是订阅费了。

为什么这类项目注定活不长

这不是道德判断，是结构判断。这类项目同时要对抗三件事：

1. 协议变更：私有接口没有稳定性承诺，平台每次发版都可能让你的实现失效
2. 风控识别：对话补全类产品的账号共享，是最容易被行为特征识别的滥用类型——同 IP、异常频率、非官方客户端指纹
3. 生态自毁：一旦有人开始批量注册、卖卡密，平台就会收紧到「所有人一起死」，这正是主项目停维护的第三条原因

三段式结局几乎固定：火 → 收紧 → 弃坑。你选择进入的时间点，决定了你要不要经历最后那段。

如果你已经上手了：止损清单

不写操作步骤，只列原则：

1. 把主账号摘出来——任何长期使用、绑定真实业务或个人资料的账号，不要放进任何账号池
2. 不要接生产流量——把它当玩具，别让任何有交付期限的事依赖它
3. 清理授权——检查该账号的登录设备与授权记录，发现不认识的就下线；必要时改密码
4. 不要转售、不要代注册、不要接码——这几件事已经从「违反 ToS」跨到可能涉法的区间
5. 做好随时关停的心理准备——不要在这条通道上构建任何你无法承担中断的流程

更划算的合规替代

如果你的真实需求是「用便宜的 API 额度调大模型」，有两条正路：

路线一：官方 API + 自建网关。 用官方发放的 API Key，在自建网关上做多 Key 轮询、限额、日志、模型映射——该有的工程能力一样不少，而且不涉及任何账号共享。同类开源网关（如 new-api、one-api 系）成熟度和社区支持都远好于一个两个月新的逆向项目。本站此前写过 ai-gateway 的部署教程，就是这个思路。

路线二：把官方额度用足。 各家都有新用户额度、学生认证、低价档模型（Flash / Lite / Mini 系列）。日常写代码、跑脚本，用便宜档位的官方 API，实际花销经常低于「订阅费 + 住宅代理 + 踩坑时间」的总和。

核心区别只有一句：官方 Key 是授权给你的，账号池里的凭证是借来的。 授权的东西可以长期规划，借来的东西随时会被收回。

评估任何「账号池 / 反代」项目的五问

以后再遇到类似的工具，按这五条过一遍，基本能判生死：

1. 它访问的是官方公开 API，还是逆向的私有接口？ 后者没有兼容承诺
2. 它需要我交出什么？ 只要涉及登录态、Cookie、扫码授权，就要按「交出账号」的严重程度来评估
3. 它的更新机制是什么？ 二进制 + 自动更新 = 把执行权限长期授予一个匿名作者
4. 它自己的 README 有没有写「禁止批量注册 / 商业转售 / 绕过风控」？ 写了，说明这就是它的主要用途
5. 它活了多久、上游还在不在？ 一个月新 + 上游已删除 = 别把任何重要事情放上去

小结

这两个项目本身不算「恶意软件」，作者也明确写了自用定位和禁止转售。但它们所依附的模式——逆向私有接口 + 账号池 + 自动化保活 + 住宅代理规避风控——注定是一笔短命的生意：

• 技术上：上游一改协议就失效，主项目已经停更
• 账号上：封号是设计内的结果，还会连坐同账号的其他服务
• 安全上：登录态托管给一个 AI 大量代写、上游已删库的新项目
• 成本上：省下的订阅费，要先付给住宅代理和踩坑时间

如果你的目的是「便宜地用上大模型」，答案从来不是把别人的账号变成你的管道，而是用官方 Key 搭自己的网关——同样是工程活，但这个网关明天还在。

参考

• workbuddy2api-panel（GitHub，已停止维护）
• workbuddy-manager（GitHub）
• One API（开源 OpenAI 兼容网关）
• New API（开源大模型网关）
• 腾讯云 CodeBuddy 官网
• 本站：AI Gateway 部署教程（自建网关思路）

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

2026 年 10 月 28 日下午至 29 日凌晨，NAS 圈炸了锅：国内外大量群晖（Synology）NAS 用户发现存储空间里的文档、照片、数据库备份被批量加密，扩展名统一变成 .L0CK3D（部分显示为 .LOCK3D，含数字 0 和 3），每个目录里都多了一份 read-me3.txt 勒索信，内容是 C3RB3R INSTRUCTIONS 和一组 6 位设备 ID，引导受害者用 Tor 浏览器访问暗网自助站点交赎金。

这件事之所以让人慌，不只是规模大，而是它打破了很多人的安全认知：受害者里既有跑最新 DSM 7.4.1 的设备，也有开了两步验证、改了默认端口、禁了 SSH 的设备。360 反勒索团队与 Solar 应急响应团队已相继披露事件，群晖官方也已确认用户数据被加密并发布安全公告。

如果你现在正在读这篇文章、并且 NAS 里有重要数据：先看第四章「中招后的黄金一小时」，那里有一条可能让你免费恢复全部数据的自救路径——前提是千万别断电、别重启。

事件时间线

受害面从家庭相册（DS918+ 等家用型号）到企业备份服务器、私有 GitLab 代码库都有，有用户报告 8TB 至数十 TB 数据被一次性加密，同机备份目录也未能幸免。

攻击特征：你的 NAS 有没有中招

对照下面几条，任意一条命中就要立刻处理：

• 文件扩展名被追加 .L0CK3D
• 各级目录和系统根目录出现 read-me3.txt，内含 C3RB3R INSTRUCTIONS 与 6 位设备 ID
• Docker / Container Manager 被卸载或容器全部消失
• NAS 风扇异常狂转、CPU 占用拉满（加密进程在跑）
• Cloud Sync 正在疯狂同步 read-me3.txt 到异地网盘（说明加密已扩散到同步目录）
• 登录 DSM 后套件异常、大量服务不可用

勒索信里的条件是：0.085 BTC，超过 5 天未付则翻倍至 0.17 BTC。攻击者提供「上传一个小于 1024KB 的文件免费试解密」来证明自己确实持有密钥——这是标准施压话术，不代表付钱一定能拿回全部数据。

技术拆解：C3RB3R 是什么

根据 360 反勒索团队与 Solar 应急响应团队的样本分析：

• 家族归属：老牌勒索家族 Cerber 的现代 Linux 变种，被暂命名为 C3RB3R
• 投放方式：恶意的拉取脚本从远端服务器（报告披露的 IOC 之一：hxxp://46[.]8[.]78[.]122/xdy5.sh）下载对应 CPU 架构（x86_64 / aarch64 / armv7l）的 UPX 加壳 ELF 二进制
• 伪装：进程伪装成 /bin/libgld（带参数 -n 308）或 /bin/qnetd（带参数 153），混在系统进程里
• 加密行为：从根目录开始多线程遍历所有挂载的存储空间，跳过 27 个系统关键目录以免把系统搞崩导致加密中断，对 187 种常见扩展名做全文件加密
• 加密算法：为每个文件生成独立的 32 字节密钥与 8 字节 nonce，使用 ChaCha8 加密，并在文件末尾固定追加 588 字节尾部数据；这 588 字节里包含一段被 AES-256-CBC 会话主密钥加密保护的 48 字节密钥记录
• 后果：会话主密钥只存在于加密期间的运行内存里，落盘的全是密文——所以断电重启后才彻底失去免费恢复的可能

一句话总结原理：文件的密钥都在尾部 588 字节里，但解开它们的那把「总钥匙」只在内存中。 这就是为什么「不要重启」是这次事件里最重要的一条。

三个免登录入侵入口

驱动之家/快科技的溯源报道指出，这波攻击不是传统「Windows 电脑中毒 → 通过 SMB 共享感染 NAS」的路径，而是攻击者针对暴露在公网的群晖设备，利用无需登录的认证前远程代码执行漏洞做全网自动化扫描攻击。目前披露的入口主要有三类：

入口一：CVE-2024-10441（群晖官方初步指向的头号元凶）

群晖官方初步排查认为攻击者利用了 CVE-2024-10441（CVSS 9.8，2024 年 12 月已修补）。该漏洞让攻击者无需任何账号密码就能从公网直达 DSM 底层——这也解释了为什么两步验证、强密码、改端口全都拦不住。

入口二：2026 年 9 月披露的两个高危漏洞

360 的报告指出本轮攻击还使用了两个今年 9 月披露的漏洞（CVE-2026-13684、CVE-2026-13639，评分口径在不同来源中标注为 9.8–10.0）。相关补丁已包含在较新的 DSM 中，但没打补丁的设备仍可被直接攻破。

入口三：套件与容器

• 原生套件：群晖安全公告 Synology-SA-26:14 涉及 PHP 核心 RCE（CVE-2026-109618、CVE-2026-109619），直接影响 MailStation、Synology Calendar 等套件——只升级 DSM 系统本体、不升级套件，入口依然敞着
• 容器链路：很多人在 Container Manager 里跑 GitLab、Confluence 等自建服务并把端口映射到公网。GitLab 的未授权 RCE（CVE-2026-110264、CVE-2026-97229）被攻破后，攻击者利用高权限容器挂载目录或宿主机逃逸缺陷，把恶意拉取脚本写进 Linux 底层的 /etc/cron.d/ 定时任务里静默潜伏

破除三个安全错觉

这次事件最有价值的部分，是它逐一击碎了几个被广泛相信的「安全常识」：

错觉一：「我升到最新 DSM 7.4.1 了，肯定没事」

Solar 团队公布的受害设备中，就有运行 DSM 7.4.1-90080 Update 1 的设备。原因有两个：一是升级前就已被人植入 /etc/cron.d/ 定时任务后门，升级不会清掉它，重启后照样继续加密；二是只升了系统本体，套件中心里的 PHP、日历等高危套件没升。所以「最新系统」不等于「已修复」。

错觉二：「我开了两步验证、强密码、禁了 SSH、改了端口」

这些防的是登录，而这次利用的是认证前漏洞——请求还没走到登录环节，攻击就已经完成。2FA 在这里一点用没有。

错觉三：「我没有 IPv4 公网 IP，只开了 IPv6，应该安全」

IPv6 也是公网。 只要设备能从外网直达，攻击面就在。评论区的实际受害者里就有只开 IPv6 的。

中招后的黄金一小时

这一节请务必按顺序操作。核心原则：断外网、保电源、保内存。

第 1 步：立刻切断外网，但不要断电

• 拔掉外网网线 / 在路由器端阻断该 NAS 的所有外网连接
• 保留局域网连接和设备电源

目的是阻止脚本回传和二次破坏，同时保住内存里的密钥。

第 2 步：绝对不要做的事

• ❌ 不要重启、不要关机——内存中的会话主密钥会永久丢失
• ❌ 不要 kill -9 强杀可疑进程——同理
• ❌ 不要重装系统、不要初始化硬盘、不要删除勒索信——这些都是取证与恢复的依据

第 3 步：冻结进程、导出内存

在本地局域网 SSH 登录 NAS，用 kill -STOP <PID> 暂停（不是杀死）可疑加密进程（如 libgld、qnetd），然后导出完整的运行内存镜像。

第 4 步：从内存提取密钥、解密文件

社区开发者 @soimy（V2EX ID Mayday9421）在 LINUX DO 直播完成了这套自救：从 16GiB 内存镜像中提取出 16 字节 IV + 32 字节 AES-256-CBC 主密钥（共 48 字节会话材料），用它解开文件尾部 588 字节里的 ChaCha8 文件密钥，逐字节无损恢复了 49GiB 的 GitLab 仓库与设计文档。

他已把完整取证流程与解密脚本开源：GitHub 仓库 soimy/c3rb3r-rescue，社区里已有多个未关机的受害者借此 100% 恢复数据。

如果已经重启/关机了怎么办

内存里的主密钥已经丢失，社区路径走不通，只能：从异地备份 / Btrfs 快照恢复；保留勒索信与日志等待官方进一步方案；不建议支付赎金——没有任何付钱必然拿回数据的保证。

未中招：今晚就做的加固清单

1. 立即关闭所有公网暴露面

• 路由器上关闭端口转发、UPnP、IPv6 入站
• 停用 QuickConnect、DDNS 直连、Cloudflare Tunnel、FRP 等一切把 DSM 暴露到公网的方式
• 远程访问统一改用 VPN 组网：Tailscale、WireGuard、ZeroTier、NetBird、Headscale 任选其一——核心是「必须先授权进网络，服务本身永不暴露公网」

2. 排查系统是否已被潜伏

检查这些位置有没有你不认识的条目：

1
2
3

/etc/cron.d/
/etc/crontab
/var/spool/cron/crontabs/

同时检查 DSM 里的「计划任务」、未知管理员账号、异常登录记录。发现可疑条目先记录证据再处理。

3. 更新系统与套件（两者都要）

• DSM 升到官方建议的最低安全版本（见下表）
• 套件中心里的所有套件（尤其 PHP、MailStation、Calendar、Synology Drive）全部升级
• Container Manager 里的容器镜像也要更新，别再让 GitLab 之类服务裸奔在公网

4. 停掉同步类任务，避免污染备份

确认安全之前，暂停 Hyper Backup、Cloud Sync、Synology Drive 等同步作业——勒索文件一旦同步上去，会把云端健康备份覆盖掉。

5. 重构备份体系（这次最痛的教训）

同机备份目录在本次事件中被一并加密，等于没有备份。正确姿势：

• Btrfs 不可变快照：快照要开、要锁，让加密进程改不动
• 异地 + 离线冷备：至少一份不联网、不同物理位置的备份
• 遵循 3-2-1 原则：3 份数据、2 种介质、1 份异地

官方回应与补丁版本表

群晖已确认用户数据被加密并发布安全公告，给出了各分支的最低安全版本：

注意：有用户反馈版本高于官方建议仍然中招，Solar 团队也表示入侵入口仍在分析、不排除存在未知漏洞。所以**「达标」只是必要条件，不等于安全**——关闭公网暴露才是根本。

常见问题

Q：只开 QuickConnect、不开端口映射，安全吗？
不算安全。QuickConnect 的实际链路仍可能把服务暴露到公网，本次事件中就有通过此类方式中招的讨论。最稳的方案是 VPN 组网。

Q：前面挂了 WAF / 反向代理能防住吗？
防不住认证前 RCE。WAF 拦的是已知特征，而漏洞利用请求对代理来说就是一条正常 HTTP 请求。

Q：黑群晖受影响吗？
受影响。漏洞在 DSM 本体与套件里，和硬件来源无关；而且黑群晖往往无法及时拿到官方补丁，风险更高。

Q：付 0.085 BTC 能拿回数据吗？
不建议。没有任何保证，且会助长攻击；未关机的情况下优先走内存提密钥的免费路径。

Q：已经关了 NAS 两天，还有希望吗？
先确认有没有 Btrfs 快照或异地备份；同时关注官方与社区后续是否公布新的恢复方案。

小结

这次事件给所有自建服务的人上了一课，结论其实很朴素：

1. NAS 不该以任何形式暴露在公网——不是改端口、不是 2FA、不是 WAF，而是根本不暴露，用 VPN 组网
2. 漏洞修补要连套件一起打，容器镜像同样要维护，「系统最新」是错觉
3. 同机备份等于没有备份，必须有不可变快照和离线异地副本
4. 真中招了先保电源保内存，那 48 字节可能是你唯一的免费出路

群晖官方公告、社区救援工具都还在更新，事态没有完全收敛。我把这次事件整理成文，希望帮到正在自查或刚中招的人——尤其是那句最容易被忽略的提醒：别急着拔电源。

参考

• Cerber 勒索攻击群晖 NAS 事件预警（360 安全资讯）
• 群晖 NAS 遭勒索病毒攻击：最新 DSM 版本也有受害报告（小众软件）
• 速速自查！群晖 NAS 惊爆大规模勒索攻击：官方证实呼吁立即更新（腾讯新闻/快科技）
• 群晖 NAS 突发 .L0CK3D 勒索病毒，内存提取密钥自救与加固全指南（AFeng Blog）
• 【勒索预警】群晖 NAS 最新版遭勒索病毒攻击（知乎·Solar 应急响应团队）
• 群晖疑出现 0day 漏洞，28-29 日凌晨大量 NAS 用户集体中招（LINUX DO）
• soimy/c3rb3r-rescue：社区开源自救工具（GitHub）

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

开店做生意，进货、卖货、记账三件事躲不开。市面上的进销存软件要么按年收费，要么数据锁在别人服务器里，要么功能重到小店铺用不上。

CF-ERP 是一个开源（MIT 协议）的无服务器进销存系统，整套跑在 Cloudflare Workers + D1（SQLite） 上——没有服务器、没有月费，Cloudflare 免费额度对个人 / 小微企业 / 店铺来说完全够用。后端 Hono 框架，前端 Vue 3 免构建单页应用，单 Worker 同时承载 API、静态页面和定时备份任务。

• 项目地址：https://github.com/love-ztm/cf-erp
• 在线演示：https://ycerp.us.ci（演示账号 admin / admin123，演示环境数据可能被其他体验者修改，别存真实业务数据）
• 开源协议：MIT

功能特点

技术架构

整个系统的架构非常克制——一个 Worker 打天下：

几个架构细节值得一提：

• 静态资源与 API 同源：wrangler.jsonc 里配置 run_worker_first: ["/api/*"]，API 请求先进 Worker，其余路径直接走静态资源，未命中回退 index.html（SPA 路由）
• schema 内嵌：rules 把 schema.sql 以文本方式打包进 Worker，每个 API 请求前幂等执行 ensureSchema——表结构不存在就自动建，列升级自动迁移，部署后零初始化步骤
• 默认管理员自举：users 表为空时自动创建默认管理员（可用 ADMIN_PASSWORD 变量或 Secret 覆盖初始密码）

成本核算：移动加权平均法

进销存系统的灵魂在成本。CF-ERP 采用移动加权平均法：

• 每次采购入库时，按 (原库存 × 原均价 + 新入库量 × 新进价) ÷ 总库存 重算该商品的移动加权成本
• 销售出库时，即时快照固化当时的成本均价——历史订单的毛利不随日后进价波动而变化
• 支持在商品管理中手动指定并锁定成本均价（锁定后不随采购流水变动）
• 任何历史单据修改或删除后，系统自动全量重放重算，确保账实严格相符

这套机制保证了「商品毛利报表」里的数字是可信赖的，而不是简单用售价减个大概成本。

部署教程

部署是一个全新空系统（含默认管理员 admin / admin123，不含任何业务数据），全程四步，五分钟内完成。

第 1 步：登录 Cloudflare 并创建 D1 数据库

1
2

npx wrangler login
npx wrangler d1 create cf-erp

d1 create 会输出一个 database_id。

第 2 步：填入 database_id

把上一步拿到的 database_id 填进项目根目录的 wrangler.jsonc：

1
2
3
4
5
6
7

"d1_databases": [
  {
    "binding": "DB",
    "database_name": "cf-erp",
    "database_id": "<你的 database_id>"
  }
]

第 3 步：部署

1

npm run deploy

Wrangler 会自动完成 Worker 打包、D1 绑定和静态资源上传，输出你的 Workers 域名（形如 cf-erp.<你的子域>.workers.dev）。

第 4 步：登录并初始化设置

访问 Workers 域名，用 admin / admin123 登录，然后进「系统设置」：

• 公司与系统配置：修改店铺名称、电话、地址、打印页脚
• 用户账号管理：立即修改默认密码，按需添加员工/销售账号并勾选权限
• 数据备份与恢复：如有历史数据，上传备份文件一键还原

两点建议

绑定自定义域名：workers.dev 域名在国内部分网络环境访问不稳定，建议在 Cloudflare 后台给 Worker 绑一个自有域名（托管在同一 Cloudflare 账号下的域名加一条 CNAME 即可），稳定且顺手。

用 Secret 管理初始密码：wrangler.jsonc 里的 ADMIN_PASSWORD 是明文变量，正式使用建议改用 Secret（Secret 会覆盖 vars）：

1

npx wrangler secret put ADMIN_PASSWORD

本地开发与测试

1
2
3
4

npm install
npm run dev              # 本地服务 http://127.0.0.1:8787
npm run db:init:local    # 手动初始化本地 D1（一般不需要，会自动建表）
node test/api.test.mjs   # 跑自动化集成测试

项目自带 61 个集成测试用例，覆盖登录鉴权、采购/销售/退货、欠款核销、成本重算等核心链路，我本地实测 61 通过 0 失败——对开源 ERP 来说，这个测试密度是数据可靠性的底气。

数据备份：双保险

ERP 数据是最不能丢的数据，CF-ERP 提供两层备份：

本地全量 JSON 备份：系统设置里一键下载全量备份（JSON 格式），随时可上传还原，适合手动定期存档。

WebDAV 远程定时备份：配置一个 WebDAV 网盘（坚果云 / 群晖 / AList 等都支持），填入地址、账号、密码和远程目录后，Workers Cron 会在每天北京时间凌晨 2 点自动把全量备份推上去。备份 URL、用户名、密码、远程目录和 cron 时间都可以在系统设置里调整，面板会显示上次备份时间和状态。

顺带说一句：这个自动备份本质上就是 Workers 的 scheduled 入口——部署时 wrangler.jsonc 里的 triggers.crons（0 18 * * * UTC 即北京凌晨 2 点）就是它的触发器。

使用建议

• 适合谁：个人副业、小微店铺、需要轻量记账的小团队——不想为 ERP 付月费、又希望数据在自己账号里自主可控的用户
• 优点：零成本、部署极简、免运维（Cloudflare 托管一切）、数据可导出可迁移、移动加权成本核算专业可靠
• 边界：D1 免费额度（每天 10 万行读、1 万行写）对单店铺场景绰绰有余，但如果是高频批量出单的团队，建议留意 Cloudflare 用量面板
• 安全提醒：部署后第一件事就是改默认密码；如果绑定了自定义域名，建议在 Cloudflare 后台开启 Access 或至少启用强密码策略

常见问题

部署后打不开 / 提示 500？

先确认 wrangler.jsonc 里的 database_id 是否已经替换成第 1 步 d1 create 输出的真实 ID。D1 未绑定正确时 API 会报错，页面可以加载但登录失败。

忘记 admin 密码怎么办？

用 wrangler d1 execute cf-erp --remote --command "DELETE FROM users" 清空用户表，重新访问系统时会用 ADMIN_PASSWORD（或默认 admin123）自动重建管理员——注意这会删除所有用户账号，业务数据仍在其他表里。

能导入之前用其他软件的数据吗？

可以先手工整理成商品/客户 CSV 借助界面录入，或者参考项目 tools/ 目录里的历史数据迁移脚本；也可以备份 JSON 后直接改 JSON 再还原。

手机上能用吗？

前端是响应式设计，手机浏览器直接访问即可完成日常开单、查库存、看报表，小票打印也支持。

小结

CF-ERP 把「进销存」这个传统上要么付费、要么自己买服务器部署的软件品类，压缩进了一个 Cloudflare 免费套餐里：四条命令部署、61 个测试兜底、移动加权成本核算、WebDAV 自动备份。对于正被记账软件订阅费困扰的小商家，或者想找个真实项目学习 Workers + D1 全栈开发的开发者，它都值得一试。

参考

• CF-ERP GitHub 仓库
• CF-ERP 在线演示
• Hono 框架官网
• Cloudflare Workers 文档
• Cloudflare D1 文档
• Wrangler CLI 文档
• Vue 3 官方文档

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

C 盘空间告急大概是 Windows 老用户最持久的痛：180GB 的系统盘，不知不觉就红了。手动找大文件像寻宝——资源管理器不会告诉你哪些文件夹在偷偷长大，设置里的存储分析只给个粗略分类，真正的「空间大户」往往藏在 AppData 这种普通用户一辈子不会点开的角落。

我的机器就是个典型例子：C 盘 180GB，已用 117GB，资源管理器里翻半天也不知道钱花哪儿了。而用 ZCode 这类智能体做这件事的思路完全不同——它擅长的不正是「遍历、统计、分析、批量执行」吗？这篇文章把我查资料 + 结合实际整理出的四步方案完整记录下来：体检 → 清理 → 迁移 → 固化。

核心原则先放在最前面：智能体负责找和算，人负责决定删什么。全程建议使用 Ask before changes（默认）模式，每一批删除操作前都要过目确认。

先搞清楚：C 盘的钱都花哪儿了

动手之前，先了解一下 Windows 上真正吃空间的几类东西（这是清理方案的知识基础）：

普通用户卡在 C 盘的往往是聊天工具文件 + 浏览器缓存 + 更新缓存；开发者还要再加包管理器缓存 + WSL 虚拟磁盘两条大项。这些正是下面清理和迁移的主战场。

用 ZCode 清理的正确姿势

在开始之前，先把「怎么指挥智能体」这件事说清楚，方法比命令本身重要。

执行模式：用 Ask before changes

清理磁盘是典型的高风险批量删除场景。ZCode 默认的 Ask before changes 模式是这里唯一合理的选择：每条删除命令、每次文件改动都会先弹出确认，你逐项过目。熟练之后，可以把「只读的体检」放到 Edit automatically 下跑得快一点，但删除操作永远不要用 Full access 自动放行。

让它先报告、后动手

一次好的清理会话分两个阶段，提示词里要显式分开：

阶段一——只体检，不删除：

1
2
3
4
5
6

扫描 C 盘，找出占用空间最大的 20 个目录和最大的 10 个文件。
重点覆盖：AppData\Local、用户 Documents、Windows 系统缓存目录、
休眠文件和虚拟内存文件的大小。
以表格输出：路径 / 大小 / 属于哪类（缓存/临时文件/聊天文件/系统文件）/
是否适合安全清理。
只读分析，不要删除任何东西。

小技巧：把「只读分析，不要删除任何东西」写进提示词，或者直接用 Plan mode，让第一轮彻底零风险。

阶段二——按清单清理：

1
2
3
4

根据上面的体检报告，只清理「缓存和临时文件」这一类：
1. 逐项列出你打算删除的目录、预计释放空间、删除理由
2. 我逐项确认后再执行
3. 执行完重新统计 C 盘可用空间，对比清理前后的变化

用 Hook 给删除操作上保险

如果经常做这类清理，可以给 ZCode 配一条 PreToolUse Hook：凡是命中 rm、Remove-Item、del 且参数里出现 Windows、Program Files 的删除命令，直接 deny。相当于给智能体的危险操作加了一道硬闸——具体写法见 ZCode 的 Hooks 配置（~/.zcode/cli/config.json 里 hooks.enabled: true 后加 PreToolUse 事件，matcher 匹配 Bash 工具，脚本里检查命令文本并返回非零退出码拦截）。

空间不足时用目标模式闭环

清理是个「执行 → 验证 → 再执行」的循环，很适合目标模式：

1
2

/goal 在不卸载任何软件、不删除任何个人文件的前提下，
把 C 盘可用空间提升 30GB 以上，所有删除操作逐项向我确认

智能体会自己循环：体检 → 提方案 → 等确认 → 执行 → 复查 → 不够就找下一个目标——不用反复喊「继续」。

第一步：空间体检

体检的目标是拿到一张「钱花哪儿了」的清单。让 ZCode 用命令行工具扫描，比图形界面快得多也细得多，例如：

1
2
3
4
5
6

# 各盘剩余空间
Get-PSDrive -PSProvider FileSystem

# 指定目录总大小（对每个可疑目录执行）
"{0:N2} GB" -f ((Get-ChildItem "C:\Users\<用户名>\AppData\Local" -Recurse -ErrorAction SilentlyContinue |
    Measure-Object Length -Sum).Sum / 1GB)

一次典型体检跑完，报告大概长这样（数字因机器而异，重点看结构）：

有了这张表，「空间去哪儿了」的谜底就揭开了——接下来的动作都有依据，而不是到处乱删。

第二步：安全清理（按风险分级）

ZCode 给出建议后，实际清理可以按下面的分级清单执行。让智能体按级别分批执行、每批确认一次，是最稳的节奏。

零风险：临时文件与回收站

一键方式（图形界面，同样是 ZCode 可以帮你调起的）：

1

cleanmgr /d C:

低风险：系统级缓存

需要确认：休眠文件与虚拟内存

这两项释放空间立竿见影，但改变系统行为，按需决定：

1
2
3
4
5

# 关闭休眠 —— hiberfil.sys 立即消失（笔记本合盖不休眠，仍可正常关机睡眠）
powercfg -h off

# 或者把休眠文件压到内存的 50%
powercfg -h -size 50

虚拟内存迁移：系统属性 → 高级 → 性能设置 → 高级 → 虚拟内存 → 更改，把 C 盘的页面文件取消「自动管理」，改设到 D 盘（初始大小可以给物理内存的 1–1.5 倍）。一台 32GB 内存的机器，这一项就能给 C 盘腾出 10GB 以上。

开发者专项：包管理器缓存

1
2

npm cache clean --force
pip cache purge

不过对开发机来说，这些缓存删了还会长回来——真正的解法在第三步的迁移。

第三步：迁移到其他盘（治本）

清理只能解决一时，迁移才是治本：让以后再产生的大文件直接落到 D 盘。假设 D 盘剩余空间充足，以下按收益从大到小。

3.1 聊天工具文件（通常是最大单项）

微信：设置 → 文件管理 → 更改目录，指到 D:\WeChatFiles，旧文件会提示迁移。QQ 同理。这一步经常能一次释放几十 GB，是普通用户收益最大的单项操作。

3.2 包管理器缓存改位置

删缓存是下策，改缓存目录是上策——以后所有缓存自动落 D 盘：

1
2
3
4
5
6
7
8
9
10
11

# npm
npm config set cache "D:\dev-cache\npm"

# pip
pip config set global.cache-dir "D:\dev-cache\pip"

# pnpm
pnpm config set store-dir "D:\dev-cache\pnpm-store"

# Yarn Classic
yarn config set cache-folder "D:\dev-cache\yarn"

Gradle、Maven、Go、Cargo 走环境变量：

1
2
3
4

GRADLE_USER_HOME = D:\dev-cache\gradle
MAVEN 的 settings.xml 里 <localRepository>D:\dev-cache\maven</localRepository>
GOPATH / GOMODCACHE   = D:\dev-cache\go
CARGO_HOME            = D:\dev-cache\cargo

让 ZCode 做这件事很合适——它可以把上面所有配置一次性执行完，再各跑一次小下载验证新位置生效。

3.3 Docker Desktop 与 WSL

Docker Desktop：Settings → Resources → Advanced → Disk image location 改到 D 盘，镜像数据整体搬家。

WSL 的虚拟磁盘（ext4.vhdx）有个著名特性：在子系统里删文件，vhdx 不会自动缩小。先在 WSL 里清理，再把磁盘压实：

1
2
3

wsl --shutdown
# 以 Ubuntu-22.04 为例，先确认 vhdx 路径，再压缩：
Optimize-VHD -Path "C:\...\Ubuntu-22.04\ext4.vhdx" -Mode Full

Optimize-VHD 需要 Hyper-V 模块；没有的话用 diskpart（select vdisk file="..." → compact vdisk）等效。整个 vhdx 也可以整体搬去 D 盘：wsl --export 导出 → wsl --import 到 D 盘新位置。

3.4 大文件夹整体搬家：mklink 目录联调

有些软件（老版本微信、某些游戏、工程目录）路径写死在 C 盘，改不了设置。这时用 NTFS 目录联调（junction）：文件实际存 D 盘，原路径仍然可用，软件毫无感知：

1
2
3

# 以把 D:\moved\WeChatFiles 接回原路径为例
robocopy "C:\Users\x\Documents\xwechat_files" "D:\moved\xwechat_files" /E /MOVE /R:1 /W:1
mklink /J "C:\Users\x\Documents\xwechat_files" "D:\moved\xwechat_files"

执行顺序很重要：先搬文件（robocopy /MOVE），再建链接（mklink /J）；操作前关闭对应软件。让 ZCode 执行时，把这两条命令拆开逐步确认——尤其确认 robocopy 完成之后再建链接。

下载、桌面、文档这些用户文件夹不必用 mklink：资源管理器里右键文件夹 → 属性 → 位置，直接改路径，Windows 原生支持。

第四步：验证与固化

清理迁移做完，让 ZCode 复跑一次体检脚本，对比前后数字——比如一次典型的成套操作下来，常见收益是：更新缓存 + Temp + 休眠文件 + 微信迁移 + npm 迁移，合计释放 30–50GB，C 盘从飘红回到从容。

想让这件事不反弹，还有两个固化手段：

1. 定时体检：用 ZCode 的 Automations 建一个每周任务，「扫描 C 盘可用空间和 Top10 大目录，环比增长超过 2GB 就输出报告」——空间被谁吃掉，一周内就能知道
2. Hook 长期护栏：保留第二步提到的 PreToolUse 拦截 Hook，给以后所有会话里的危险删除命令兜底

安全红线：这些事不要让智能体做

最后把红线列清楚，写进你的提示词或 AGENTS.md 都行：

• 不要删 C:\Windows、C:\Program Files 下的任何东西（更新缓存和 DISM 是仅有的两个例外，且用上面给定的官方方式）
• 不要用「强制删除/递归删除」去清 AppData——正在运行的软件的缓存目录删了轻则丢登录态，重则丢配置
• WinSxS 不要手动删，只能走 DISM
• pagefile.sys、swapfile.sys 不能直接删文件，只能通过虚拟内存设置改
• system32 报错为「拒绝访问」是保护机制，绕过它的办法只有一个：不要绕
• 大规模删除前，先让智能体把清单写进一个 txt 备着，误删了还有据可查

常见问题

ZCode 会不会乱删文件？

只要你待在默认的 Ask before changes 模式，每一条删除命令都要你点确认，它「想乱删」也没有执行机会。真正要注意的是不要图省事切到 Full access 跑清理。

为什么我删了 WSL 里的文件，C 盘还是没变大？

因为 ext4.vhdx 只增不减——Linux 侧删除只是标记空间空闲，虚拟磁盘文件不会自动收缩，需要 Optimize-VHD 或 diskpart 压实，见 3.3。

DISM 跑了很久正常吗？

StartComponentCleanup 在补丁装得多的机器上跑十几分钟到半小时都正常，中途别关机。加 /ResetBase 可以清得更狠，但代价是已装更新无法再卸载，介意就别加。

清理和迁移，哪个优先？

先体检，按报告来。一般顺序是：先删零风险缓存（快、立刻见效），再迁大文件（慢、治本），最后做系统级瘦身（DISM、休眠文件）。如果只剩几个 GB 急着救急，前两步就能救回来。

小结

这套流程的本质，是把「清理 C 盘」从一门玄学变成一条流水线：

1. 体检——智能体扫描统计，把空间去向变成一张表
2. 清理——按风险分级执行，人在环上逐批确认
3. 迁移——缓存改配置、聊天文件改目录、虚拟磁盘搬家、大文件夹上 junction
4. 固化——Hook 拦危险命令，定时任务防反弹

智能体的价值不在于「替你删」，而在于它能把散落在几百个目录里的空间去向在几分钟内算清楚，然后把方案摆到你面前——决定权始终在你手里。C 盘飘红的朋友，值得花半小时跑一遍这套流程。

参考

• Microsoft：释放 Windows 中的驱动器空间
• Microsoft Learn：DISM 命令行选项
• Microsoft Learn：powercfg 命令行选项
• Microsoft Learn：mklink 命令
• Microsoft Learn：robocopy 命令
• npm 官方文档：npm config
• pip 官方文档：缓存机制
• Docker Desktop：设置文档
• Microsoft Learn：WSL 文档
• ZCode 官网

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

2026 年 9 月 23 日清晨，四川成都都江堰市上空出现了一个「不速之客」：多位市民抬头看到一个形似飞艇的物体悬浮在高空，纷纷拿出手机拍摄，视频和照片迅速在本地社交平台刷屏，随后登上微博热搜，引发全网热议。

「UFO」三个字一出现，评论区必然分裂成两派：一派高呼「外星人来了」，另一派说「不就是个气球」。这篇文章把 9 月 23 日事件的已知信息、官方回应、合理推测完整梳理一遍——最后你会发现，最可能的答案既不是外星人，也不是普通气球，而是一类正在快速发展的航空器。

事件回顾

先看目前媒体公开报道中比较一致的信息：

几个目击特征值得单独强调：

• 长时间悬停、几乎没有位移——这一点和持续上升的普通气球明显不同，也是它引发大规模关注的关键
• 飞行姿态与普通飞机、无人机有明显区别——目击者的直观感受是「这东西不像我平时见过的任何飞行器」
• 白色半透明——在阳光下呈半透明状，说明囊体可能是透光的柔性材料

官方回应：气象部门排除了探空气球

事件发酵后，媒体（四川观察）记者向气象部门求证，得到的回复非常明确：

成都施放探空气球仅有温江国家气候观象台一处，且是在规定的时间施放。都江堰上空出现的这个物体，并非气象探空气球。

这个排除是有理有据的，原因有三层：

1. 施放点唯一：成都地区的探空气球只有温江国家气候观象台一个施放点，都江堰当天没有施放作业
2. 时间固定：探空气球按业务规范在固定时刻施放（全球气象业务统一），不是想放就放
3. 形态不符：探空气球是球形、持续上升的，而这次目击的物体是细长椭圆、定点悬停——形态和运动特征都对不上

排除探空气球之后，这个物体在「已知的常规气象活动」里就没有解释了——这正是它成为「不明飞行物」的原因。

先纠正一个概念：UFO ≠ 外星飞船

每次出现不明飞行物，「外星人」必然是流量最高的猜测。但这里必须把概念说清楚：

UFO（Unidentified Flying Object）的字面含义就是「不明飞行物」——仅仅代表当下暂时无法识别的空中物体，不等于外星飞船。

回顾国内过往的同类目击事件，市民拍到的「神秘物体」经过后续调查，绝大多数最终被证实是人造物体或大气光学现象，常见类型包括：

• 商业广告飞艇
• 大型高空气球
• 无人机编队
• 云层光影折射

所以面对这次都江堰事件，正确的姿势不是二选一站队「外星人 or 气球」，而是列出所有技术上说得通的候选解释，等官方调查结论。

它可能是什么：三个主流推测

截至发稿，空管、公安等主管单位尚未发布最终身份结论，没有任何官方或研究机构「认领」这个飞行器。但业内和科普圈的主流分析，指向三类人造浮空器：

1. 系留浮空艇（可能性最高）

靠氦气等轻质气体提供浮力、通过地面缆绳实现定点停留的浮空平台，可以长期悬停在一个位置上空，常用于：

• 地质灾害观测
• 环保监测
• 安防巡查

成都平原周边这类设备已有落地先例——天府新区此前部署的「云端号」就是同类系留浮空器。系留浮空艇从外形（细长椭圆）和驻空特征（定点悬停）上都和这次目击描述最匹配。

2. 平流层科研飞艇

用于大气环境监测、对地观测等科研任务的高空长航时飞艇。这类飞艇通常也是白色半透明外观（囊体材料透光），具备定点驻空能力。

3. 高空风能发电平台

网传说法中还有一类「S4000」式的高空风能发电平台：用大型气囊把发电和缆绳系统送到数千米高空取风发电，再通过缆绳回传电力。有分析指出，都江堰周边山地、河道、景区多，在本地做环境感知或新能源测试并不突兀。

关于「为什么是半透明的」

有分析认为，透明或半透明的外观可能与飞艇气囊采用的特殊柔性材质有关（透光膜材本身就是浮空器的常见选择），也可能是在特定光线和角度下日光反射造成的视觉现象。

背景：临近空间为什么这么热

要看懂这类目击事件为什么越来越多，得把视角拉到临近空间（距地 20–100 公里）。

平流层飞艇、高空气球、太阳能无人机都属于 HAPS（高空平台系统）。它们的独特价值在于：

• 比卫星离地近——通信延迟低，光学遥感分辨率高
• 比普通飞机覆盖广——单平台驻空时间长、覆盖范围大
• 成本低——不需要火箭发射，可回收重复使用

典型应用包括：通信基站（应急通信、6G 空天地一体化）、光学遥感、红外探测、气象与环境载荷。2026 年 MWC 上海展会上就展出过平流层飞艇模型，指向 6G 空天地一体化网络；国内科研也在攻关 20 公里级柔性飞艇的成套技术——囊体材料、氦气渗漏控制、自主定点、太阳能储能。

临近空间应用正在全球范围内升温，各国都在抢通信、观测、灾害预警的入口。这意味着：以后城市上空出现「长悬停的白色大飞艇」，大概率会从罕见新闻变成常见现象。

截至目前的状态

把时间线整理到发稿为止：

目前没有任何官方或研究机构认领这个飞行器，最终结论有待相关部门进一步通报。

如何理性看待

给关心这件事的读者三条建议：

1. 别急着站队。从「外星人」到「气球」之间的巨大空档里，存在系留浮空艇、科研飞艇、风能平台等大量合理候选，等调查结果比猜更有效率
2. 不造谣、不信谣、不传谣。「外星人到访」这类博眼球的猜测式谣言，在权威结果出来前一律别转发
3. 以官方通报为准。是否系留、定高多少、归属单位、空域是否报批、载荷是监测还是发电——这些信息一旦官方公布，谜底自然揭晓

我的判断是：这是一次典型的「新型浮空器被当成 UFO」事件。它有趣的地方不在于猎奇，而在于它恰好让我们看见了临近空间产业正在悄悄起飞。

参考

• 都江堰上空现不明飞行物（都市快报·微博）
• 成都都江堰上空现不明飞行物，气象部门：此物体并非气象探空气球（四川观察/搜狐）
• 成都都江堰上空出现不明飞行物！市民拍到白色透明物体，气象部门回应（网易）
• 成都都江堰悬停不明飞行物，形似飞艇，气象部门排除探空气球（新浪）
• 都江堰上空現不明飛行物 白色透明 長時間懸停（阿波羅新聞網）
• 都江堰上空拍到不明飞行物！形似飞艇悬停高空（今日头条）
• 都江堰飞艇状物体引关注！”神秘飞艇”是回应，还是巧合？（搜狐·秒懂科普）
• 都江堰上空现不明飞行物，气象部门已排除探空气球，最有可能是什么？（知乎）

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

用过官方 API 的人都知道几个痛点：价格贵（Claude Opus 5 官方定价不便宜）、需要海外信用卡、一个平台只有一种模型。AI 大模型中转站（也叫 API 代理、API 中转）就是解决这些问题的：它们把多家模型商的 API 统一成一个 OpenAI 兼容接口，你注册一个账号、拿到一个 Key，就能在一个地方调用 Claude、GPT、Gemini、DeepSeek、GLM、Kimi 等几十款模型，价格往往只有官方的几分之一。

本文是我亲测在用的 7 家中转站推荐，每家都附注册链接。价格和模型列表会随时间变化，以各平台官网为准。

推荐列表一览

逐一介绍

1. LlmHost — 模型全、分组灵活

🔗 点击注册

模型覆盖：47 款以上，涵盖 GLM-5.3、GPT-5.6 系列、Claude 全系（含 Fable 5、Opus 4-6）、Kimi K2.6/K3、Qwen 3.5/3.6/3.7、MiniMax M2.5/M3、MiMo V2 Pro、DeepSeek V4 等。

分组体系：自动分组包括「付费」「35折分组」「DeepSeek V4 Flash 折扣」，不同分组对应不同折扣力度，灵活选择。

亮点：

• 有 ox-alpha-free 免费模型可用
• 模型覆盖面广，从国产 GLM/Kimi 到海外 Claude/GPT 一站式覆盖
• 支持 OpenAI 兼容格式，无缝对接主流客户端

2. TaBiToken — Claude 专属中转

🔗 点击注册

模型覆盖：2 款（Claude Opus 5、Claude Opus 5 Thinking）

定价：输入 $0.8 / M tokens

适用场景：只需要 Claude Opus 5 的用户，价格适中，界面简洁。

3. GoRouter — Claude 最低价中转

🔗 点击注册

模型覆盖：2 款（Claude Opus 5、Claude Opus 5 Thinking）

定价：输入 $0.3 / M tokens，是目前这几家里 Claude 单价最低的。

适用场景：高频使用 Claude Opus 5、对成本敏感的用户。$0.3 的定价相比官方和同类中转站有明显优势。

4. JustWoker — Claude 中转

🔗 点击注册

模型覆盖：2 款（Claude Opus 5、Claude Opus 5 Thinking）

基于 New API 搭建，需注册登录后查看定价。支持 OpenAI 兼容格式，适合需要备用 Claude 通道的用户。

5. Vsllm（维云）— 模型最全的全能选手

🔗 点击注册

模型覆盖：68 款以上，是这 7 家中模型数量最多的。

定价亮点：

• GLM-4.6V Flash：0.05 ratio，极低
• Gemini 3.1 Flash Lite：0.025 ratio
• Qwen 3.6 Plus：0.03 ratio
• DeepSeek V4 Flash 有折扣分组

适用场景：需要同时用到多家模型、尤其是 Gemini 系列齐全的用户。一站式覆盖 GPT/Claude/Gemini/国产全家桶。

6. KKToken — Claude 中转

🔗 点击注册

模型覆盖：2 款（Claude Opus 5、Claude Opus 5 Thinking）

基于 New API 搭建，需注册后查看定价。支持 OpenAI 兼容格式，适合作为 Claude 备用通道。

7. TokenFreePerDay — 每日免费额度 + 价格亲民

🔗 点击注册

模型覆盖：34 款以上

最大亮点：有 free 免费模型，且多数付费模型定价非常亲民：

覆盖厂商：GLM、GPT、DeepSeek、Kimi、Qwen、Gemini、MiniMax、MiMo、Claude 等。

适用场景：预算有限但想体验多款模型的用户，尤其是需要 Gemini 和 DeepSeek Flash 的场景。

通用使用教程

这 7 家中转站全部基于 New API 或兼容系统搭建，使用方式完全一致：

第一步：注册账号

点击上方对应的注册链接，用邮箱注册即可。

第二步：获取 API Key

登录后在后台找到「令牌」或「API Keys」页面，创建一个新的 Key。格式通常是 sk-xxxxxxxxxxxx。

第三步：配置 Base URL

把 API 的 Base URL 填入你的客户端：

第四步：选择模型

在客户端的模型选择框里输入对应模型名（如 claude-opus-5、gpt-5.4、glm-5.3 等）。不同中转站支持的模型名可能略有差异，以各平台定价页为准。

常见客户端

• ChatBox：桌面/手机端，支持自定义 API
• OpenCode / ZCode：AI 编程智能体，可配置模型提供商
• ChatGPT-Next-Web：自部署 Web 客户端
• LobeChat：功能丰富的 Web 客户端
• 任何支持 OpenAI API 的工具：直接把 Base URL 和 Key 填进去即可

注意事项

1. 价格会变。各中转站的定价随上游模型商调整而变化，本文数据基于 2026 年 9 月实测，注册前请以官网最新价格为准。
2. 不要存敏感数据。中转站本质上是第三方代理，你的请求会经过它们的服务器。敏感代码、商业数据建议直接走官方 API。
3. 多备一个。建议同时注册 2-3 家，一家挂了可以切到另一家。中转站的稳定性不如官方，多通道是基本操作。
4. 关注分组和折扣。很多中转站有分组机制（如「35折分组」「DeepSeek 折扣」），同一模型不同分组价格可能差几倍，注册后先看定价页再选。
5. 免费额度要珍惜。部分中转站提供每日免费额度或免费模型，适合轻度使用和测试，但重度使用还是需要充值。
6. 确认模型是否在售。中转站的模型列表会动态调整，某个模型可能临时下架。重要业务别只绑定一个中转站。

小结

没有完美的中转站，只有适合你场景的组合。建议从免费额度试起，确认速度和稳定性后再充值使用。

参考

• New API 开源项目

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

2026 年 8 月 29 日，长鑫科技宣布自主研发的最新一代低功耗内存 LPDDR6 实现量产，并将首批搭载于小米 18 Fold 折叠旗舰手机。按照长鑫的官方说法，这是全球 LPDDR6 产品首次落地商用——中国存储企业第一次在高端内存标准上，抢在三星、SK 海力士之前完成产品首发量产。

同一天，雷军发文祝贺长鑫「非常了不起」，并宣布：玄戒 O3 首家支持长鑫 LPDDR6，小米 18 Fold 全球首发搭载。央视财经对此的评价是：为中国半导体协同突破「提供了新样本」——「从『芯』到『存』，从单点技术突破到产业链协同发力」。

这篇文章把这次事件的内容（LPDDR6 到底是什么、长鑫做到了什么）、实际意义（为什么重要）和影响范围（会波及哪些领域）一次讲清楚。

事件回顾

先把整个时间线捋一遍：

一句话总结：从 JEDEC 标准发布到长鑫产品量产，只用了约 13 个月。

内容解读

LPDDR6 是什么

LPDDR（Low Power Double Data Rate）是面向智能手机、平板等移动设备的低功耗 DRAM 标准，由国际标准组织 JEDEC 制定。2025 年 7 月发布的 JESD209-6，就是这个家族的第六代，官方定位是「显著提升移动设备与 AI 应用的性能、能效与安全」。几个关键技术点：

• 双子通道架构：LPDDR6 的通道位宽为 24bit，由两个 12bit 子通道组成，同时保持最小访问间隔 32 字节——访问粒度更灵活，对小数据量的随机访问（正是 AI 推理负载的典型特征）更友好
• 速率区间：标准初始数据速率为 10.667Gbps，最高定义速率 14.4Gbps
• 安全增强：针对移动与 AI 场景补充了安全性设计
• 封装形态扩展：面向 PC 的 LPDDR6 CAMM2 等扩展形态也在推进中

JEDEC 在新闻稿里大量强调 AI——这不是蹭热度。端侧大模型的瓶颈恰恰在内存带宽和容量上，LPDDR6 的架构就是冲着这个去的。

长鑫首发产品做到了什么

三个值得注意的点：

1. 12.8Gbps 不是标版上限，而是「实用档位」。JEDEC 标准最高定义到 14.4Gbps，三星 2025 年展示的原型速率同为 12.8Gbps——长鑫首发的这个速率，已经和三星原型站在了同一水平线上。首发选择 12.8Gbps 是典型的工程决策：先把「标准起始速率之上、整机稳定可量产」的这一档做出来。
2. 1295 Ball POP 封装说明它就是给手机准备的。POP（Package on Package）是内存直接堆叠在 SoC 之上的封装方式，是旗舰手机的标配形态，对基板、良率和厚度控制的要求都很高。
3. 带宽提升 20% 配合实测数据。玄戒 O3 搭配 LPDDR6 的实测内存带宽为 113.8GB/s，比上一代玄戒 O1 提升 48%——内存和 SoC 是协同设计的，不是单方面内存快。

「全球首发」的含金量

存储行业过去几十年的惯例是：新标准由三星、SK 海力士、美光定义节奏，先发量产，其他厂商跟进。LPDDR6 这一轮，三家海外巨头都在推进，原本的共同目标是 2026 年下半年量产——结果长鑫抢先落地。

更要紧的是代差的历史变化：过去国产存储与国际巨头的新品代差普遍在半年以上，这一轮不但追平，还压缩成了「先发」。从 2026 年 3 月送测、8 月初验证尾声、8 月底官宣量产，节奏和海外第一梯队完全同步甚至更快。

首发组合：国产 SoC + 国产内存

首发机型小米 18 Fold 的含金量不止是「用了国产内存」：

• 玄戒 O3（8 月 24 日发布）：3nm 工艺，十核全大核（C1-Ultra + C1-Premium + C1-Pro，最高 4.35GHz），16 核 G2-Ultra NX GPU，NPU 200TOPS 张量算力，安兔兔跑分 522 万（首个突破 500 万的旗舰 SoC）
• 小米 18 Fold：小米首款阔折叠形态旗舰，9 月上市；小米平板 9 Pro Max 同步搭载玄戒 O3

央视财经点出了这件事的本质：小米「敢于让国产核心器件在高标准的旗舰手机中接受市场检验」，以量产产品完成严格验证，牵引国产核心器件加速走向规模应用。旗舰机是内存可靠性、功耗、兼容性最苛刻的试炼场——能进旗舰，才算真正出师。

实际意义

对长鑫：从跟随者到规则参与者

过去长鑫的角色是「追赶者」——做 DDR4、LPDDR4X，再追 LPDDR5。LPDDR6 全球首发意味着它第一次站在了新产品周期的起点上：享受完整的产品生命周期红利，而不是在生命周期末端靠价格竞争。Counterpoint 研究副总裁 Neil Shah 的评价很直白：问题「不在于长鑫能否跻身三大内存厂商之列，而在于何时能做到」。

资本市场的态度也说明了预期：长鑫科技 7 月底上市后市值一度站上 3.98 万亿元、居科创板首位；2026 上半年营收 1503.1 亿元（同比 +873.64%），归母净利润 776.05 亿元、同比扭亏为盈。行业普遍关注其 IPO 募资将如何投向 HBM 和 LPDDR6 产能扩张。

对中国半导体：验证了「协同突破」的路径

这次首发的样板价值在于链路完整：JEDEC 标准内参与 → 长鑫按标准设计产品 → 送样验证 → 国产 SoC（玄戒 O3）首家支持 → 旗舰整机首发 → 规模出货。内存厂商、SoC 厂商、整机厂商三方在同一个时间窗内完成协同，这在国产半导体史上是第一次。

它还回答了一个老问题：国产高端器件「造出来」和「用起来」之间的鸿沟怎么跨——答案是让旗舰机当场验证，用市场反馈倒逼迭代，而不是等完美再上场。

对消费者：旗舰体验的直接提升

对普通用户来说，LPDDR6 带来的变化是可感知的：

• 端侧 AI 更流畅：大模型推理吃内存带宽，带宽提升 20% 直接换来响应速度和可运行的模型规模
• 游戏与多任务：折叠屏大屏多任务、高负载游戏更依赖内存吞吐
• 能效改善：低功耗设计意味着同等负载下更省电，对折叠屏这种电池吃紧的形态尤其重要

对全球 DRAM 格局：四强时代开启

Counterpoint 数据显示，2026 年 Q2 三星、SK 海力士、美光合计占全球 DRAM 收入约九成，长鑫约 7%——但已是全球增长最快的 DRAM 供应商（全球第四、中国第一）。LPDDR6 首发是一个信号：在 2026 年 DRAM 供给紧缺、持续涨价的超级周期里，长鑫拿到了切入高端市场的门票。竞争格局从「三强」向「3+N」演变，对下游整机厂意味着多了一个有分量的供应商选项。

影响范围

智能手机与端侧 AI（最先落地）

LPDDR6 的影响首先发生在手机上。未来两年安卓旗舰会把 LPDDR6 作为标配硬件，长鑫的先发意味着国产高端内存有机会进入更多旗舰机型的物料清单。随着良率爬坡和多平台适配完成，渗透会从折叠旗舰逐步下探。

PC（LPDDR6 CAMM2）

JEDEC 的 LPDDR6 引入了 CAMM2 等面向 PC 的封装扩展，AI PC 的本地大模型负载同样吃带宽。长鑫若跟进 CAMM2 形态，将直接影响笔记本内存的供应格局。

智能汽车

智能座舱正在变成「车里的旗舰手机」——多屏、语音大模型、辅助驾驶感知都吃内存带宽。长鑫官方对 LPDDR6 的应用展望里，智能汽车被明确列出，车规市场是下一个增量。

服务器与 AI 数据中心

低功耗内存正在服务器领域扮演新角色（如 SoC 集成大内存容量的架构路线）。长鑫官方表示 LPDDR6 未来将在移动设备、服务器等领域广泛运用，端侧与数据中心的内存带宽需求共振，这是产能扩张的底气所在。

产业链上下游

存储量产从来不是一家公司的事。据腾讯新闻 7 月报道，长鑫已提前布局供应链——引入新的封装基板供应商海信电子，推动从卷对卷工艺向面板级封装转型。LPDDR6 上量会带动基板、封装、测试、设备等一整条国产配套链。

国际竞争与价格

三星、SK 海力士的 LPDDR6 也在上市路上，三家的量产窗口重叠意味着高端 DRAM 的竞争会更激烈。叠加当前 DRAM 供给紧缺的涨价周期，长鑫的新增产能每多一分，全球定价博弈的天平就多一分变数——这对下游整机厂是利好，对海外巨头的超额利润是稀释。

冷静看待：首发之后的挑战

首发是里程碑，但不是终点，几个现实问题需要时间回答：

1. 良率与产能爬坡。首发不等于大规模供应，小米 18 Fold 的备货量、后续机型的导入节奏，取决于良率爬坡速度。这是所有新存储产品的必经之路。
2. HBM 差距仍在。AI 数据中心最紧缺的是 HBM，这是长鑫与国际巨头差距最大的品类；LPDDR6 的 IPO 募资投向之一就是 HBM，追赶需要时间。
3. 生态验证需要周期。第一款机型首发只是开始，多平台适配、车规与服务器级验证都需要按年计的周期。
4. 份额差距客观存在。7% 对九成，高端市场的实质性突破要靠连续几代产品维持，一两款首发不能定论。

小结

长鑫 LPDDR6 量产这件事，技术参数上是一次常规迭代（12.8Gbps、16GB、带宽 +20%），但行业位置上是一次非常规突破：中国存储第一次在新一代高端内存标准上全球首发商用，且和国产 SoC、国产整机在同一天官宣协同——「从『芯』到『存』」的产业链闭环首次在旗舰级产品上跑通。

值得记住的时间点：JEDEC 标准发布后 13 个月，长鑫完成了从对齐标准、送样验证到量产商用的全过程，把过去「半年以上」的代差变成了「先发」。至于这能否转化为持续的份额与利润，看接下来的产能、良率与 HBM 进展——但至少在这一代，发令枪是长鑫打响的。

参考

• 长鑫官宣LPDDR6量产，雷军称小米将首发（观察者网）
• 长鑫宣布LPDDR6内存已量产，称打破海外厂商长期垄断（搜狐）
• 长鑫科技：自研LPDDR6芯片性能较LPDDR5X全面跃升（IT之家）
• 长鑫存储：LPDDR6内存正式量产（第一财经）
• 全球首发！长鑫科技官宣LPDDR6量产（东方财富/北京商报）
• 长鑫LPDDR6内存芯片送样验证加速量产（腾讯新闻）
• 小米18 Fold首发搭载长鑫LPDDR6+玄戒O3！央视：为中国半导体协同突破提供了新样本（新浪科技/快科技）
• 小米18 Fold折叠屏手机首发玄戒O3芯片，9月正式上市（IT之家）
• LPDDR6内存标准正式发布：JEDEC JESD209-6（电子工程专辑）
• JEDEC LPDDR6 介绍材料（jedec.org）
• 长鑫科技LPDDR6量产站上世界第一排（雪球）

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

ZCode 是智谱（Z.ai）推出的一款智能体开发环境（ADE，Agentic Development Environment），官方定位是「面向长周期任务的全功能智能体开发环境」。和传统的代码补全插件不同，ZCode 把「智能体」而不是「手写代码」放在中心位置——你描述目标，它自己读项目、写代码、跑命令、验证结果。

• 官网：https://zcode.z.ai
• 文档：https://zcode.z.ai/en/docs/install
• 最新版本：v3.9.2（2026-08-26）
• 应用本身免费，模型能力需要你自己提供（GLM Coding Plan 订阅、BigModel 资源包，或任意兼容的 API Key）

本文中的功能说明与配置路径均来自官方文档与本机实际安装目录，实测环境为 Windows 10 x64 + ZCode 桌面版。

功能介绍

安装

支持的平台

官方文档明确支持：macOS（Apple Silicon / Intel）、Windows（x64 / ARM64）、Linux（x64、ARM64，提供 AppImage / DEB / RPM）。

下载地址

打开 https://zcode.z.ai 点击 Download ZCode 会自动匹配你的系统。也可以直接用 CDN 直链（以 v3.9.2 为例）：

Windows 安装包约 155 MB。把版本号替换成新版本即可获取对应文件，建议以官网下载页为准。

各平台安装步骤

Windows

1. 下载 .exe 安装包
2. 双击运行，按向导完成安装
3. 从开始菜单或桌面快捷方式启动
4. 若被杀毒软件拦截，把安装目录加入白名单

macOS

1. 下载并打开 .dmg
2. 把 ZCode.app 拖进「应用程序」文件夹
3. 从启动台打开

如果提示「应用已损坏」，是隔离属性导致的，执行：

1

xattr -dr com.apple.quarantine /Applications/ZCode.app

Linux

AppImage 方式：

1
2

chmod +x ZCode-*.AppImage
./ZCode-3.9.2-linux-x64.AppImage

部分发行版还需要 fuse 依赖（Ubuntu / Debian 缺 libfuse2 时无法启动）：

1

sudo apt install libfuse2

.deb / .rpm 走各自发行版的包管理器安装即可。

首次启动

整个流程官方给的预估时间是「约 2 分钟」：

1. 引导页 — 可以直接「开始使用 ZCode」，也可以走数据迁移向导。注意迁移范围有限，目前只导入 Claude Code 和旧版 ZCode Agent 的会话，之后也能在设置里再迁移。
2. 选择工作区 — 指定一个项目目录。如果不想绑定仓库，可以在工作区菜单里选「在项目外工作」。
3. 连接模型 — 左下角 Connect 按钮，提供三个入口：Connect Z.ai、Connect BigModel、Use API Key。
4. 冒烟测试 — 随便发一句「列出当前目录的文件」，确认智能体能正常跑起来。

连接模型

ZCode 本身不含模型额度，必须先接上模型服务。配置文件落在 ~/.zcode/v2/config.json。

方式一：账号快连（推荐）

设置 → 模型服务商 → 选择 Z.ai 开放平台 或 BigModel，走登录流程后 Key 会自动回填。用 GLM Coding Plan 订阅走账号授权时不需要手填 Base URL，路由是自动的。

方式二：手填 Base URL + API Key

不同套餐对应的端点不能混用，这是最常见的踩坑点：

三类端点的区别：

• /api/coding/paas/v4 — 仅 Coding Plan 可用
• /api/paas/v4 — OpenAI 兼容通用端点，用于资源包和余额计费
• /api/anthropic — 同样服务资源包，走 Anthropic 协议，是 ZCode 的默认协议

其他模型服务商

除 GLM 外，ZCode 也支持接入：

也可以添加任意 Anthropic / OpenAI 兼容的自定义服务商。BigModel 新用户有 5 天试用额度：GLM-5.3 每天 300 万 tokens，GLM-5.3-Flash 每天 500 万 tokens。

两个容易踩的坑

• 终端环境变量不会被继承。你在 shell 里 export 的 GLM Key，桌面应用读不到，必须在应用内配置。
• 代理必须在应用内设置。设置 → 通用里的 HTTP Proxy 留空不等于跟随系统，ZCode 完全忽略 HTTP_PROXY 这类环境变量。所以经常出现「终端能联网、应用连不上」的情况。改完代理需要重启应用。另外，代理不覆盖 SSH 连接和 Web 远程控制通道。

界面与基础用法

添加上下文

聊天框左下角的 + 按钮，或直接输入对应触发字符：

粘贴长文本会自动转成附件。在回复、推理过程、代码块或工具结果里选中一行，会浮出「添加到当前任务」按钮。

执行模式（重要）

输入框聚焦时按 Shift + Tab 循环切换四档权限：

思考档位

输入框右下角模型名旁边的思考图标，三档：Low（追速度）、High（日常平衡）、Max（默认，最深，适合架构设计和硬 bug）。

侧边会话

不打扰主任务的并行对话，四种打开方式：选中文本后点「在侧边会话中提问」、/side 或 /btw 命令、右侧面板 + 菜单、起始页。它会借用主会话的历史作为上下文，但界面是空的，并且可以调工具、改文件。每个任务每窗口只有一个，关掉即不可恢复。

分叉（Fork）

鼠标悬停在已完成的助手回复上点 Fork，会生成一个「Fork of <原标题>」的新任务，继承到那一刻的历史、模型、思考档位。原任务继续跑。注意文件不会回滚——两个会话共享同一个工作区。

目标模式：让它自己「继续」

长任务最烦的是反复打「继续」。Goal Mode 就是解决这个的：

1

/goal 把 src/ 下所有 TypeScript 类型错误清零，且保持现有测试全绿

运行机制：每一轮结束后有一个独立的校验环节判断目标是否达成——不达成就输出下一步并自动开启下一轮，达成就收尾出总结。校验是证据驱动的：改动的文件、命令输出、测试结果算证据，而计划、清单、听起来很有信心的文字不算。任何未完成的 to-do 都会阻止收尾。

两种情况会被拒绝并给出原因：Plan mode 下（计划模式的目的是先定方案，和自动连轮冲突）和任务正在运行时。

配合 Full access 或 Edit 模式打断最少。目标状态在关闭再打开会话后仍然保留。

适合什么目标：一句话能说清、但需要很多轮才能做完的事——模块重构且测试保持通过、清零全部类型错误、把 Lighthouse 分数拉过 90。目标要可校验，「让它更快一点」这种不行。

子智能体：并行研究代码库

内置两个角色，都不能改名或删除，但可以给它们单独指定模型和思考档位：

• general-purpose — 默认的通用角色，拥有全部工具，适合自成一体的实现、验证跑批、并行工作
• Explore — 只读的代码库研究专家，用来梳理调用链、摸清架构、收集证据。它「不创建、不修改、不移动、不删除文件」

主智能体判断需要隔离上下文或并行研究时会自动通过 Agent 工具调起。你也可以显式指挥：

1

先用 Explore 研究一下这个模块的调用链，再决定怎么改

自建子智能体（Beta）

设置 → Subagents → New，保存后会写入 ~/.zcode/agents/<name>.md，下次运行生效。

Frontmatter 字段（camelCase，大小写敏感）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

---
name: code-reviewer
description: 审查当前改动的代码质量、边界条件和安全问题。需要代码评审时使用。
model: glm-5.3
thoughtLevel: high
color: blue
tools:
  - Read
  - Grep
  - Glob
maxTurns: 20
injectAgentsMd: true
---

你是一名严格的代码评审者。逐条给出问题、影响范围和修复建议……

几个容易踩的点：

• name 和 description 必填，缺任一个文件会被忽略并给出诊断
• description 直接决定自动选中率，写得越准越容易被自动调用
• tools 省略或写 * 表示继承全部（含 MCP）；一旦自定义列表就是穷举的，会把所有 MCP 工具排除掉（WebSearch / WebFetch 不受影响，因为它们不是 MCP）。需要 MCP 就手动写 mcp__<server>__<tool>，通配符无效
• thoughtLevel 只在指定了具体 model 时生效，注意不是 reasoningEffort，未知字段会静默失败
• injectAgentsMd 默认开启，会注入 ~/.zcode/AGENTS.md 和工作区的 AGENTS.md；Explore 永远不注入

限制：目前只支持用户级（~/.zcode/agents/），子智能体不能再派生子智能体，只能看到会话启动时已连接的 MCP 服务。

前台 vs 后台：前台子智能体并行跑但会阻塞主任务；后台的让主任务继续，自己稍后回报。后台的 Explore 被限制为只读工具。

指令文件 AGENTS.md

ZCode 读两个指令文件，全局在前、工作区在后，工作区文件视为权威：

• ~/.zcode/AGENTS.md — 个人跨项目偏好（回复语言、评审风格、本地工作流约定）
• <项目根>/AGENTS.md — 项目约定（架构边界、日志规范、测试要求、提交策略）

没有多级合并、不扫描子目录、不展开 @import / @include。CLAUDE.md 只作为一次性迁移来源，运行时不会持续读取。

内置 /init 命令针对的是当前工作区的 AGENTS.md。

我自己的工作区 AGENTS.md 长这样，纯文本约定就能显著改善智能体行为：

1
2
3
4
5
6
7
8
9

# 工作区约定

## 网络代理
- 唯一代理：socks5h://192.168.2.8:1081（仅 SOCKS5 模式可用）
- 所有访问境外服务的操作一律走此代理

## 博客写作流程
- 修改 source/_posts/*.md → 提交推送 hexo 分支 → npx hexo generate → npx hexo deploy
- 每篇新文章必须包含 ai: true 与 post_ai 摘要

另外还有一个独立的 项目记忆（Project Memory），由智能体自己写：设置 → 通用 → Memory（默认关闭）。它在成功的轮次后提炼可复用事实，新会话自动加载。代价是额外 token，且只对新会话生效，应用内不能浏览或清除，只作用于主对话，子智能体既不读也不写。

技能（Skill）

技能是「可复用的工作方法」。命令适合存提示词，技能适合装一整套方法论。

目录结构

目录名就是技能名，也是聊天里引用的 token：

1

~/.zcode/skills/<skill-name>/SKILL.md

也可以导入到当前项目作用域。要打包分发就放进插件，必须是扁平的 skills/<name>/SKILL.md 布局，套一层分组目录会导致识别不到。

SKILL.md 格式

Frontmatter 只有两个字段，都是必填：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

---
name: code-review-checklist
description: 按固定清单审查代码改动，覆盖边界条件、错误处理、并发安全和日志规范。需要代码评审或提交前自查时使用。
---

# 代码评审清单

## 何时使用
用户要求评审代码、提交前自查，或询问改动有什么风险时。

## 步骤
1. 用 git diff 拿到完整改动
2. 逐文件检查以下维度……

## 输出格式
按「文件:行号 → 问题 → 影响 → 建议」输出。

约束：

• 缺 name 或 description 会整个被忽略，原因在设置诊断里能看到
• description 上限 1024 字符，超了是整个技能作废而不是截断，长内容写正文
• 正文超过 100KB 会在加载时截断

调用方式

聊天框输入 $ 选技能，再接你的需求：

1

$code-review-checklist 审查我当前的改动

选中的技能会渲染成一个标签。输入 / 也能看到 Skills 分组。

上下文预算（这点很关键）

每一轮都会注入所有已启用技能的元数据：名字 + 最多 250 字符的描述摘要。正文是懒加载的，只在调用时才读。所有技能共享一个固定的元数据预算，溢出后会降级成只注入名字——这会直接毁掉模型自动选技能的能力。

所以技能装得越多，自动触发越不准。技能在面板里能看到但从来不触发，官方给了四个原因：元数据降级、description 太含糊、子智能体的 tools 白名单排除了技能工具、父插件被禁用。

内置技能

zcode-configuration-guide 默认启用、零配置，它是配置问题的「地图」。配套还有一批诊断技能：

• diagnosing-skills — 技能没被发现 / 不触发 / 被同名遮蔽
• diagnosing-commands — / 命令缺失 / 被覆盖 / frontmatter 报错
• diagnosing-mcp — MCP 连不上 / 工具不出现 / 超时
• diagnosing-hooks — Hook 不触发 / matcher 不匹配 / 脚本没有执行权限
• diagnosing-plugins — 插件不在列表 / 安装失败 / 组件缺失

目前没有独立的技能市场。设置 → Skills 里的导入图标可以扫描 Claude Code、Codex CLI、OpenClaw、Augment、Windsurf 的目录一键导入，可选软链接（跟随源变化，依赖路径不变）或复制（独立，不再同步）。

远程 SSH / WSL 工作区需要在工作区头部 Sync 下拉里手动 Sync Skill，因为用户级技能是本地的。

插件（Plugin）

一个插件可以同时打包 技能、命令、子智能体、MCP 服务、Hooks 五类组件。开关插件会一次性注册或撤销它的全部组件。

安装

设置 → Plugins 打开市场（需要先打开一个工作区，否则提示「Open a workspace to manage plugins」）。分两个板块：

• Public — 官方策展目录，分 Developer Tools、Productivity、Utilities、Guides、Templates 等分类
• Personal — 你自己添加的源，Claude Code 市场是预置的

点卡片一键安装，新装的插件默认启用。齿轮图标进入「管理已安装」，能看到版本、来源标签、组件数量，支持启停、状态筛选、检查更新和卸载。

官方插件市场

ZCode 官方市场地址是 https://cdn-zcode.z.ai/zcode/official-plugin/marketplace.json，当前收录：

内置插件（随应用发布）：

内置插件可以禁用但不能卸载——卸载会写一个抑制标记，升级也不会自动装回来。

插件结构

manifest 查找顺序是 .zcode-plugin/plugin.json（推荐），兼容回退到 .claude-plugin/plugin.json。它是唯一必需的文件：

1
2
3
4
5
6
7
8
9
10

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "示例插件",
  "author": { "name": "你的名字" },
  "skills": "skills",
  "commands": "commands",
  "hooks": "hooks/hooks.json",
  "mcpServers": ".mcp.json"
}

只有 name 是必填，约束为 ^[a-z0-9][a-z0-9._-]{0,127}$。组件目录约定：commands/、skills/<name>/SKILL.md、agents/、hooks/hooks.json、.mcp.json。

channels、lspServers、outputStyles、settings 会被记录但不执行。插件提供的 MCP 服务键名会变成 plugin:<插件名>:<服务名>。

模板变量：${ZCODE_PLUGIN_ROOT}（兼容 ${CLAUDE_PLUGIN_ROOT}）、${CLAUDE_PLUGIN_DATA}、${CLAUDE_PROJECT_DIR}、${user_config.key}。

⚠️ 安全提示：官方文档原话是「启用插件即授予代码执行信任」。第三方插件可以拉起本地进程、读取智能体继承的环境变量。装之前先看一眼它的 hooks/hooks.json 和脚本。

自己发布插件

更新检测是拿市场条目里的版本号和已安装的 plugin.json 对比，所以发布时一定要同步 bump marketplace.json 的版本号，否则用户收不到更新提示。

市场清单必填 name 和 plugins，条目 source 支持相对路径，或 directory / github / git / file / url / npm 形式的对象。

MCP 服务

添加方式

设置 → MCP Servers → New MCP Server。表单模式覆盖大部分场景：选作用域、填名字（比如 memory）、类型保持 stdio、命令填 npx、参数填 -y @modelcontextprotocol/server-memory，Key 和路径放到环境变量里。

远程服务选 HTTP 或 SSE 填 URL，认证信息放 Headers。也可以切到完整配置模式直接粘 JSON，{"server-name": {...}} 和 {"mcpServers": {...}} 两种形状都接受。

导入图标会扫描这些文件：~/.claude/settings.json、~/.codex/config.toml、~/.config/opencode/opencode.json、~/.agents/mcp.json。原文件不动，导入结果落到 .zcode 里并默认启用。

配置文件路径

注意这个不对称：用户级原生配置在 .zcode/cli/ 下，工作区级直接在 .zcode/ 下。

配置示例：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "mcp": {
    "servers": {
      "memory": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-memory"],
        "env": {},
        "enable": true
      }
    }
  }
}

字段：command、args、env、enable。远程条目用 URL 和可选 headers 代替 command。

加载规则

• 先读工作区配置，再读用户配置，两者都会出现在列表里
• 同一作用域内 .zcode 优先：只要它定义了任何服务，同级的 .agents/mcp.json 就整个被跳过，不做合并
• 禁用会写 "enable": false，字段缺失即启用
• 面板里的编辑只写 .zcode，永远不写 .agents
• 同名冲突时用户级覆盖工作区级

传输方式

• stdio — 本地命令执行，凭据只能走环境变量
• HTTP / SSE — 远程，支持可选 headers 和 OAuth

OAuth 服务（官方举例 Figma 官方 MCP）启用 OAuth 后，服务行上会出现「Open authorization」按钮，点它在系统浏览器里授权，ZCode 拿到 token 后重连。它不会自己弹浏览器窗口。

推荐的起步服务：智谱的 zai-mcp-server（视觉）、web-search-prime、web-reader，大多需要智谱 API token。

⚠️ 打开一个项目会自动连接它配置里的所有 MCP 服务，这些服务能跑命令、动文件、访问网络。打开不可信仓库前先看一眼 .zcode/config.json。

Hooks

七个事件钩子，可以在关键节点拦截、注入上下文、做权限门禁：

配置

只有用户级生效：~/.zcode/cli/config.json，且必须写 hooks.enabled: true（默认关闭）。工作区的 hooks 配置会被整个丢弃。插件的 hooks/hooks.json 自动发现，任何插件贡献了 Hook，Hook 运行器就会自动启用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "hooks": {
    "enabled": true,
    "timeoutMs": 60000,
    "maxOutputBytes": 32768,
    "events": {
      "PreToolUse": [
        {
          "matcher": "Write|Edit",
          "hooks": [
            {
              "type": "process",
              "command": "python3",
              "args": ["scripts/audit.py"],
              "enabled": true,
              "timeoutMs": 8000
            }
          ]
        }
      ]
    }
  }
}

matcher 语法：缺省、空串或 * 匹配全部；只含字母、数字、下划线和 | 的字符串按精确名单处理（Write|Edit）；其他一律编译成 JS 正则，非法模式会被跳过并给出诊断。Agent / Task 是别名，会解析成真实工具名。

协议：ZCode 通过 stdin 发一行 JSON + 换行，字段同时提供 camelCase 和 snake_case 别名（session_id、cwd、hook_event_name、tool_name、tool_input、tool_use_id、transcript_path、permission_mode）。退出码 0 解析 stdout，2 是拦截快捷方式，其他非零表示该 Hook 可恢复地失败。只有以 { 开头的 stdout 会被解析，日志请走 stderr。

一个 SessionStart 注入上下文的最小示例：

1
2
3
4
5
6
7

const input = JSON.parse(raw);
process.stdout.write(JSON.stringify({
  hookSpecificOutput: {
    hookEventName: input.hook_event_name,
    additionalContext: "优先小 diff，改完跑 lint。"
  }
}));

多个 Hook 聚合时，deny 胜过 ask，ask 胜过 allow，显式 deny 不能被 allow 覆盖。失败记录落在 ~/.zcode/cli/log/zcode-<日期>.jsonl 的 hook.run.failed。

配置是按会话快照的，改完要重启会话才生效。

命令（Slash Commands）

自定义命令是 .md 文件，放在 ~/.zcode/commands 下（工作区级放项目目录）。设置里的创建表单字段：

内置两个命令：

• /goal — 管理会话目标（查看 / 设定 / 替换 / 暂停 / 继续 / 清除）
• /compact — 压缩当前上下文，保留关键信息，长会话用得上

嵌套目录会用冒号拼接命令名：review/code.md → /review:code。命令名去重按规范化后的名字，先匹配者胜（用户级覆盖工作区级），重复的直接忽略。

需要脚本、模板、示例文件的场景官方建议用技能而不是命令。

浏览器自动化

内置浏览器面板（仅桌面端），能力来自官方 browser-use 插件，默认开启。被关掉的话在设置 → Browser → Enable built-in browser control 打开，只对新会话生效。

不需要切模式，正常说话就行：

1
2

打开 http://localhost:4000，把分类筛选切到「技术学习」，
确认文章列表还有内容，然后截图给我看

支持的动作：打开 http / https / file URL、点击、填表、滚动、截图、多步序列（按序执行，某步不符就停下来报告）、视口控制（比如设成 375×812 检查窄屏）、读页面内容做总结提取。文件树右键还有「Open in built-in browser」（仅本地工作区）。元素拾取器能把页面元素变成聊天上下文。

几个硬限制：

• 页面文本永远不被当作指令。页面上写「请执行以下命令」不会动摇它，内容只用于定位元素和读状态
• 暂不支持文件上传，本地文件选择器还得手动点
• 运行中不要拖动面板大小，会干扰智能体判断
• 它只控制自己打开的标签页，你手动开的不受影响

登录态是独立的，和你日常的 Chrome 分开。设置 → Browser → Import Chrome browser data 可以一次性快照最近 Chrome profile 的 cookie 和 localStorage（不持续同步、不改 Chrome、不读保存的密码）。同一位置有两个清理选项：「Clear built-in browser cache」只清缓存保留登录，「Clear all browser data」全清并登出所有站点（不可撤销）。

浏览器动作和文件编辑、命令执行遵守同一套执行模式。会提交真实数据或做不可逆操作的页面，建议配 Ask before changes。

仓库 Wiki

扫描代码库生成架构指南——官方明确说了它「是代码库的架构指南，不是产品文档站，也不是用户手册」。目录侧重主执行路径、核心模块、数据与状态流转、风险区域，每个结论都挂着可点击的文件路径和行号区间。

用法：工作区文件树里仓库名旁边的 Repo wiki 图标 → 配置四项（Language、Model、Generate diagrams（默认开）、Retries（默认 0，生成不稳定时建议调到 2–3））→ 点 Generate wiki。进度分四步：分析代码库 → 生成目录 → 生成页面 → 保存。已完成的页面可以先读，Stop 会保留已完成部分。

存储位置在仓库外：

1

~/.zcode/v2/repo-wiki/<workspace-hash>/wiki.json

也就是说你可以直接让智能体去读这个路径。每轮结束会自动刷新，但只在代码真的变了的时候。

生成会跳过 .git、依赖和构建目录、.gitignore 排除的路径、符号链接目标，以及文件名看起来像密钥的文件——不过「像 tokenService.ts 这样的普通源文件不受影响」。

限制：每个仓库同时只能有一个任务、只保留一个语言版本（换语言重生成会替换掉）、单页不能单独重生成、没有版本历史。

自动化任务

左侧栏 Automations 入口（在项目工作流里，不在设置里）。分两类：定时任务按时间规则触发，空闲时段任务没有时间表，排队等有空余算力时免费跑。

三种创建方式：

1. 表单 — 「Create scheduled task」，填 Task title、Schedule、Instructions，加一个「Project / permission / model / thought level」工具条
2. 聊天 — 创建按钮旁的箭头选「Create in chat」，输入框会预填一句可编辑的话，比如「每个工作日早上 9 点，汇总这个项目的代码变更和待跟进项」
3. 模板 — 四个预填选项：Weekday standup digest、Daily risk scan、Friday release brief、Wednesday doc sync check，全是只读分析，只用仓库里可验证的事实

没有裸 cron 字段，只能选频率：Hourly / Daily / Every weekday / Weekly / Monthly / Custom。Custom 打开重复规则对话框，能设单位（小时到年）、每 N 个单位、指定周几 / 月内某天 / 某些月份 + 时分，月度重复还能选按日期或按序数星期（比如「第三个周一」）。时间用本机时区。

「Run now」立即触发一次，不影响时间表、运行次数和启停状态。

每次触发的输出留在一个会话里。从聊天创建的任务绑定在那个会话上，每次运行都回报到同一处。详情页在 Settings 和 History 之间切换，History 记录每次触发（包括因为机器睡眠被跳过的），并链到对应会话记录。

限制：电脑必须醒着、应用必须开着；漏掉的一次性运行只记为跳过，不会补跑；上限是跨所有项目 20 个任务，暂停 / 完成 / 失败的也占位；只能针对当前窗口打开的本地项目；手机远程控制里不可用。

无人值守跑的任务，权限模式格外重要。只做报告就锁在只读，除非你真的想让它自主改代码。

远程开发

点 Projects 旁的 + → Remote Connection，向导四步：选类型 → 填配置 → 连接 → 选目录。

• SSH — 可以选一个 SSH config 别名自动带出 Host / Port / Username / 密钥路径，认证支持密码或私钥（可带 passphrase）。「Resource download method」决定组件是桌面端下载再上传，还是让远端直接从 ZCode CDN 拉
• WSL — Distribution 和 Linux user 都可留空走默认。不建议用 root 连，工作区文件可能变成 root 所有，普通账号改不动
• Docker — 从运行中的容器里选，或手填名字 / ID。底层靠 docker exec 和 docker cp

要求：目标上要有 POSIX shell，不支持原生 Windows 远程主机（本机 Linux 请用 WSL）。Docker 需要守护进程在跑、容器已启动、项目目录可达、工具链（shell、Git、Node.js 等）齐备。

限制：

• 跳板机不支持 — 内置 SSH 客户端忽略 ProxyJump / ProxyCommand，请改用本地端口转发
• 设置里的 HTTP 代理不覆盖 SSH 和 Web 远程控制
• 配置同步（Sync Skill / Sync MCP / Sync Plugin）是手动的、仅用户级、不覆盖已有远端条目，支持 SSH 和 WSL 但不支持 Docker。MCP 密钥是原样传输的，敏感类型和路径类型的插件选项会被跳过
• 首次连接会慢，因为要预置远端服务和智能体运行时，后续会复用

账号、模型配置和全局设置留在桌面端；文件、命令、Git 和智能体执行都发生在目标机上。

手机远程控制

扫码模式

左下角侧栏的手机图标打开 Mobile Remote Control。对话框左边是二维码和链接，右边是 Bot Channel。扫码适合短时使用，机器人适合跨天反复用。

手机上能做什么：

• 任务主页 — 列出工作区和任务，可按工作区或时间线分组，按创建或更新时间排序，下拉刷新，在已有工作区里新建任务，重连掉线的远程工作区
• 会话视图 — 看智能体回复、执行步骤、进度，底部输入框追加指令，回复支持复制、点赞点踩和分叉

手机上什么都不跑。本地工作区在你的桌面上执行，SSH 目标在远程主机上，WSL 用选定的发行版，Docker 用目标容器。手机只是把指令递进桌面已经打开的那条连接里。同时只能连一个手机页面。

🔐 链接本身就是凭据——「拿到它的任何人都能操作你的窗口」。关掉对话框不会结束会话，要真正终止得点 Stop。重新生成二维码会立刻作废之前的链接，怀疑泄露就重新生成。桌面端必须保持运行和在线。

限制：手机上不能新建 SSH / WSL / Docker 连接，那些参数得在桌面填；已注册但断开的远程工作区可以从手机重连，但连接动作还是桌面做的。

机器人通道

目前只支持两个平台：

• 微信 — 扫码登录自动绑定，一步搞定
• 飞书 — 扫码在飞书开放平台创建应用（确认名称和头像，点「立即创建」），然后把 ZCode 生成的限时绑定命令（形如 /bind C67356）发给这个应用

钉钉、Discord、企业微信官方说在后续版本支持。

绑定后机器人能：报告状态、创建任务、切换项目、切换模型、更改运行模式、调整回复详细度。管理项包括启停、连接状态、解绑、删除、回复粒度，以及限制机器人能打开哪些工作区。

飞书 / Lark 有个特殊行为：总是用流式卡片回复，所以粒度设置（Standard / Full / Summary）对它不生效。回复在同一张卡片里原地更新，工具调用是折叠的。需要你做决定时，当前卡片冻结，问题单独发一张卡片，之后再起一张新卡片继续。

使用示例

下面是几个我实际跑过的场景，能看出 ADE 和普通补全工具的差别。

示例一：读源码定位问题（而不是猜）

Hexo 博客的文章链接是中文标题转码后一长串 %E4%B8%AD...，我想换成英文短链。直接问「怎么改」大概率会得到「在 frontmatter 加 slug 字段」这种答案——但这是错的。

1
2
3

permalink 已经改成 :year/:month/:day/:slug/，并且给所有文章的
frontmatter 加了 slug 字段，但生成出来的目录还是中文。
读 node_modules/hexo/dist/ 里的源码找出 :slug 到底从哪里取值。

智能体读了 node_modules/hexo/dist/plugins/processor/post.js，在第 49 行找到 data.slug = info.title;，其中 info 来自 parseFilename(config.new_post_name, path)；又核对了 preservedKeys 只有 {title, year, month, day, i_month, i_day, hash}，不含 slug。

结论：:slug 取的是 .md 文件名，frontmatter 里的 slug 完全不起作用。真正的解法是重命名文件。这种「读源码给证据」的能力，是靠猜的工具给不了的。

示例二：Explore 子智能体做代码库调研

1
2

先用 Explore 摸清这个项目的主题配置是怎么加载的，
把所有引用头像 URL 的地方都列出来，再决定改哪几处

Explore 只读、独立上下文，跑完只把结论汇总回主对话——不会把几十个文件的原文塞进主上下文。它找到了 5 处引用：favicon、avatar.img、preloader.avatar、pwa.favicon_32_32、pwa.favicon_16_16。少改一处，浏览器标签页图标就还是旧的。

示例三：目标模式跑长任务

1
2
3

/goal 把 source/_posts/ 下所有中文文件名改成语义化英文短名，
保持 git 记录为纯重命名（R100），清掉 frontmatter 里无用的 slug 字段，
然后重新生成站点确认没有残留的中文目录

这个任务实际跑了好几轮：重命名 → 生成 → 发现 public/ 里同时存在新旧两套目录 → 定位到 db.json 缓存 → rm -rf public db.json → 重新生成 → 校验通过。目标模式的价值就在这——中间失败一次它自己会诊断并继续，不用我盯着打「继续」。

示例四：技能封装重复流程

我把博客的写作规范做成技能，每次写文章只需要一句 $blog-post 写一篇 XXX 部署教程，它就知道要带 ai: true + post_ai 摘要（且摘要里不能出现英文逗号，否则主题的 ai_abstract.js 会按逗号切分随机取一段）、要有 ## 参考资料、结尾要有固定的三个推荐链接。

这类「有固定套路但细节容易漏」的流程最适合做成技能。

示例五：浏览器自证改动

1
2

博客本地起在 4000 端口。打开首页，检查头像是不是新换的那张，
再点进任意一篇文章确认 AI 摘要框正常渲染，两处都截图

改完前端能自己验证，比我手动开浏览器点一遍快得多，而且截图留了证据。

常见问题

应用要钱吗？

应用本身免费，但模型能力要你自己提供：智谱系（GLM Coding Plan 订阅、BigModel 资源包或余额、Z.ai）、企业渠道，或团队批准的自建服务。

为什么终端里配好的 Key 应用读不到？

终端环境变量和桌面应用是相互独立的。必须在应用内配置：Quick Connect 走账号，或在「管理模型」里手填 Base URL + API Key。

终端能联网，应用连不上？

大概率是代理。设置 → 通用里的 HTTP Proxy 留空不代表跟随系统，ZCode 完全忽略 HTTP_PROXY 环境变量。填上代理并重启应用。注意代理不覆盖 SSH 和 Web 远程控制。

模型一直卡在 Loading？

两个方向：网络到不了模型服务，或者账号 / Key 没有额度和模型访问权限。

明明是百万上下文，为什么显示 200K？

缺少窗口元数据的模型会回落到 200,000。模型 ID 带 [1m] 后缀会被自动当成 1,000,000，否则以你手填的值为准。Coding Plan 的 GLM 模型窗口是固定的、不可编辑。

为什么还没到上限就开始压缩上下文？

压缩是故意提前触发的：预留输出空间 + 约 13,000 token 安全缓冲，输出预留上限 21,000，合计扣掉约 34K。所以 128K 窗口在 94K 附近就会压缩，而且触发判断还会算上当前轮工具结果的实时估算。没有用户可调的阈值。

技能面板里有，但从来不触发？

四个原因：元数据预算溢出导致降级成只注入名字、description 写得太含糊、子智能体的 tools 白名单排除了技能工具、父插件被禁用。装太多技能会直接拖垮自动选中率。

Linux AppImage 起不来？

多半缺 libfuse2（Ubuntu / Debian 用 apt 装）。从终端启动能看到具体报错，GPU 相关的崩溃可以加 --disable-gpu 走软件渲染。

浏览器登录完成但不跳回应用，是 zcode:// 协议处理器没配对——常见原因是用了 sudo、挪动了 AppImage 位置、或者 deb 和 AppImage 同时装了。检查一下：

1

xdg-mime query default x-scheme-handler/zcode

保持 AppImage 在一个固定路径。

换电脑怎么迁移配置？

要带走的：cli/config.json、v2/config.json、AGENTS.md，以及 agents/、skills/、commands/ 目录。

不要迁移 credentials.json 和 telemetry-state.json——这两个必须留在原机。

~/.zcode/cli/exec 能删吗？

应用完全关闭的情况下可以删，代价只是丢历史命令输出。

版本号在哪看？

Windows 和 Linux 在 Help → About ZCode，macOS 在 ZCode 菜单里。

小结

用了一段时间下来，ZCode 和「AI 补全插件」不是一类东西。差别集中在三点：

1. 它会去读源码找证据，而不是凭印象给答案（示例一里那个 :slug 问题就是典型）
2. 目标模式 + 子智能体让长任务真的能一口气跑完，中间失败它自己诊断继续
3. 技能 / 插件 / MCP / Hooks 四层扩展加上 AGENTS.md，能把团队规范固化成智能体行为

上手路径建议：先装好连上模型，用几天默认的 Ask before changes 熟悉节奏；然后写一个工作区 AGENTS.md 把项目约定固化下来；再把重复流程做成技能；最后按需接 MCP 和插件。别一上来就装几十个技能——上下文预算会溢出，反而让自动选中变得更差。

参考

• ZCode 官网
• ZCode 安装文档
• ZCode Agent 文档
• 目标模式文档
• 技能文档
• 插件文档
• MCP 服务文档
• Hooks 文档
• 子智能体文档
• 浏览器自动化文档
• 远程开发文档
• 手机远程控制文档
• 常见问题
• 更新日志

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客

ai-gateway 是一个基于 Cloudflare Workers + Hono 框架构建的 AI 提供商 API 聚合网关，实现「一个 API 调用所有模型」的聚合能力。它支持多密钥轮询、健康检测、自动故障转移、密钥自动恢复等高级特性，并内置 OpenCode 免费模型，默认开箱即用。整个项目采用 TypeScript 开发，前端使用 Hono 服务端渲染，管理后台为卡片式 UI，支持移动端。

• 项目地址：https://github.com/yutian81/ai-gateway
• 开源协议：Apache 2.0
• Stars：44+

功能特点

技术栈

• 兼容日期：2025-07-01
• 兼容标志：["nodejs_compat"]

项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

ai-gateway/
├── src/
│   ├── index.ts               # 入口文件，路由注册
│   ├── types.ts               # TypeScript 类型定义
│   ├── config.ts              # 默认配置
│   ├── storage.ts             # KV 存储层
│   ├── auth.ts                # 认证系统（Session + Bearer Token）
│   ├── proxy.ts               # API 转发核心（密钥轮询 + 健康检测 + 自动恢复）
│   ├── opencode.ts            # OpenCode 官方 API + 公共镜像回退
│   ├── admin.ts               # 管理 API
│   ├── pages.ts               # 前端页面模板（HTML/CSS 服务端渲染）
│   ├── pages.css.ts           # 样式（38KB）
│   └── shared.js.ts           # 前端共享 JS 工具函数
├── worker-proxy/              # 独立代理脚本
│   ├── agentrouter.js         # Agent 路由代理
│   ├── cline.js               # Cline 代理
│   ├── cline-auth.py          # Cline 认证辅助（Python）
│   └── opencode.js            # OpenCode 代理
├── .github/
│   └── workflows/
│       └── deploy.yml         # GitHub Actions 自动部署
├── package.json
├── wrangler.toml
├── tsconfig.json
├── README.md
├── API.md                     # API 完整文档
├── design.md                  # 设计系统规范
├── opencode-cdn.md            # 多 CDN 代理部署指南
└── LICENSE

部署方式一：GitHub Actions 自动部署

这是推荐的部署方式，推送到 main 分支后自动构建部署。

1. Fork 项目仓库

访问 ai-gateway 项目，先给项目点个 ⭐，然后点击右上角 Fork，将仓库克隆到你的 GitHub 账号下。

2. 创建 KV 命名空间

1. 登录 Cloudflare Dashboard
2. 进入 Workers 和 Pages → KV → 创建命名空间
3. 输入名称，例如 AI_GATEWAY_KV，点击创建
4. 记下 KV namespace ID，备用

3. 配置 GitHub Secrets 和 Variables

在 Fork 的仓库中，进入 Settings → Secrets and variables → Actions：

Secrets（密钥）：

Variables（变量）：

如何获取 CF_ACCOUNT_ID： 登录 Cloudflare Dashboard，右上角头像下拉菜单中可见，或从 URL 提取：https://dash.cloudflare.com/ACCOUNT_ID/...

4. 触发部署

在仓库 Actions 页面，找到 Deploy to Cloudflare Workers，点击 Run workflow → Run workflow。

部署流程会自动：

1. 检出代码并安装依赖
2. 生成包含 KV 绑定和管理员凭据的 wrangler.toml
3. 执行 npm run build 构建
4. 通过 Wrangler Action 部署到 Cloudflare Workers

部署成功后，访问 Worker 生成的默认域名（如 ai-gateway.你的用户名.workers.dev），或绑定自定义域名。

部署方式二：Cloudflare Dashboard 手动部署

如果你不习惯用 GitHub Actions，也可以直接在 Cloudflare Dashboard 中手动部署。

1. 创建 Worker

1. 登录 Cloudflare Dashboard
2. 进入 Workers 和 Pages → 创建 → Workers
3. 选择 连接到 Git，授权 GitHub，选择 Fork 的仓库
4. 使用默认构建设置，点击 保存并部署

2. 配置环境变量

部署完成后，进入 Worker → 设置 → 变量和机密，添加以下变量：

OPENCODE_MIRRORS_URL 默认值：

1
2
3

https://opencode.ai.cmliussss.net/zen/v1
https://opencode.fastly.cmliussss.net/zen/v1
https://opencode.gcore.cmliussss.net/zen/v1

[!NOTE]
三个默认镜像 URL 在部署 workflow 中已内置，手动部署时建议一并配置。

3. 绑定 KV

Cloudflare Dashboard 会自动创建 KV 命名空间。进入 Worker → 设置 → KV 命名空间，确认绑定名称为 KV。如果是手动创建的 KV，需要手动添加绑定。

4. 绑定自定义域名

在 Cloudflare Dashboard 中，为 Worker 添加自定义域名（如 ai.你的域名），然后在 DNS 设置中添加相应的 CNAME 记录。

API 接口

公开接口

管理后台接口（Session Cookie 鉴权）

API 转发接口（Bearer Token 鉴权）

模型 ID 格式：providerId/modelId（例如 opencode/deepseek-v4-flash-free）

请求示例：

1
2
3
4
5
6
7
8
9
10
11
12

# 获取模型列表
curl -H "Authorization: Bearer sk_cf_xxxxxxxxxxxxx" \
  https://你的域名/v1/models

# 调用聊天补全
curl -X POST https://你的域名/v1/chat/completions \
  -H "Authorization: Bearer sk_cf_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/deepseek-v4-flash-free",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

密钥健康系统

ai-gateway 内置了一套完善的密钥健康管理系统：

失败判定规则：

密钥恢复机制：
已降级的 Key 在 5 分钟冷却期后会获得一次重试机会：

• 重试成功 → 恢复权重，回到健康队列
• 重试失败 → 再次进入冷却

OpenCode 自动回退

OpenCode 提供商有特殊的智能回退逻辑：

1. 配置了 API Key → 优先尝试官方 API（https://opencode.ai/zen/v1）+ 用户 Key
2. 官方 API 失败 → 尝试公共镜像（随机起点，每个最多一次）
3. 未配置 API Key → 跳过官方 API，直接尝试公共镜像（使用 Bearer public）
4. 全部失败 → 返回官方 API 的存储错误响应

模型过滤：OpenCode 仅展示以 -free 结尾的免费模型和 big-pickle 模型。

配置说明

环境变量

默认配置（src/config.ts）

1
2
3
4
5

const PROXY_KEY_PREFIX = 'sk_cf_'       // 代理密钥前缀
const OPENCODE_DEFAULT_URL = 'https://opencode.ai/zen/v1'
const KEY_HEALTH_COOLDOWN_MS = 5 * 60 * 1000  // 5 分钟冷却
const KEY_HEALTH_MAX_FAILURES = 5              // 连续失败降级次数
const SESSION_TTL = 7 * 24 * 60 * 60          // Session 有效期 7 天

默认提供商（自动初始化）

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "id": "opencode",
  "name": "OpenCode",
  "baseUrl": "https://opencode.ai/zen/v1",
  "apiType": "openai",
  "apiKeys": [],
  "models": [
    {"id": "deepseek-v4-flash-free", "enabled": true},
    {"id": "mimo-v2.5-free", "enabled": true},
    {"id": "nemotron-3-ultra-free", "enabled": true},
    {"id": "hy3-free", "enabled": true}
  ],
  "enabled": true
}

KV 存储键