Z.AI ZCode Coding Plan → OpenAI/Anthropic 兼容網關(Go 版,現為主線)。
把 Z.AI Coding Plan 賬號池包裝成標準 API:多賬號輪詢(優惠額度優先)、驗證碼全自動求解、 額度與套餐到期監控、OAuth 登錄、賬號級出站代理、活動套餐自動領取、賬號歸檔, 單二進制交付(前端已內嵌,無外部運行時)。
📦 歷史沿革:本項目原為 Python 實現,現已由 Go 重寫版取代成為主線。 Python 舊版保留在
python-legacy分支(僅歸檔維護,不再更新)。
| 端點 | 協議 | 說明 |
|---|---|---|
POST /v1/messages |
Anthropic Messages | 流式/非流式,字節級透傳 |
POST /v1/chat/completions |
OpenAI Chat | 本地轉換為 Anthropic Messages,含工具調用 |
POST /v1/responses |
OpenAI Responses | 服務 Codex CLI(無狀態模式;previous_response_id 返回 400) |
POST /async/v1/messages |
Anthropic 異步 | ticket + keepalive + 流中斷語義 |
GET /v1/models |
雙兼容超集 | Anthropic 與 OpenAI 形態字段並存 |
/admin/* |
— | 內嵌 React 管理後台 |
/guest |
— | 訪客帳號提交頁(需管理員開啟邀請碼) |
對外三種請求格式,內部統一走 Anthropic Messages 上游管道:選號循環、驗證碼求解、 錯誤分類(401/402/429 碼族/3010/F001)、賬號狀態機與用量統計只維護一份。
# 下載現成產物(Releases 頁:linux × amd64/arm64)
# 或源碼構建:
go build -o zcode2api ./cmd/zcode2api
./zcode2api serve # http://127.0.0.1:3000
# 驗證碼自動求解:首次啟動自動下載補丁 Chromium(約 200MB,無需 Python);
# 也可用 ZCODE_CAPTCHA_BROWSER_BIN 指定已有的瀏覽器二進制
ZCODE_CAPTCHA_BROWSER=true ./zcode2api serve首次啟動橫幅輸出後台密碼與網關 API Key(也可 CLI 設定)。
瀏覽器求解不可用時自動回退人工回填(後台 /admin/captcha),功能不中斷。
zcode2api serve [--port 3000] 啟動網關 + 後台 UI
zcode2api login zai [--no-browser] OAuth 登錄 Z.AI 並入池(自動領取活動套餐)
zcode2api add-account zai <name> <jwt|key>
zcode2api accounts [zai] 查看賬號列表
zcode2api remove-account <provider> <id|name>
zcode2api quota 查看各賬號實時額度
zcode2api status 配置概覽
zcode2api set-admin-key <key> 設置後台密碼
zcode2api export [file] / import <file> 賬號導出/導入(與 python-legacy 互通)
交互式管理腳本與 Docker 方案見 deploy/README.md。
sudo ./deploy/manage.sh # 交互式選單:安裝/更新/卸載/狀態/服務控制或非交互:
sudo ./deploy/manage.sh install # 二進制 + systemd(已實測)
sudo ./deploy/manage.sh install --port 3010 --user zcode
sudo ./deploy/manage.sh update # 更新(自動比對 Release 版本)
sudo ./deploy/manage.sh uninstall # 卸載(--purge 連數據刪除)
sudo ./deploy/manage.sh docker-install # Docker(未驗證)安裝完成後自動啟動服務,首次啟動的後台密碼與網關 API Key 只顯示一次,請立即保存。
⚠️ Docker 方案未經驗證,不保證可用。 倉庫內的Dockerfile與docker-compose.yml為參考實作,從未經docker build實測(開發環境無容器運行時)。 請自行驗證與調整;本專案不對 Docker 路徑提供支援承諾。
💡 驗證碼瀏覽器:首次使用時自動從 cloakbrowser.dev 下載補丁 Chromium (SHA256SUMS + Ed25519 簽名校驗,GitHub Releases 兜底),緩存於
CLOAKBROWSER_CACHE_DIR,零 Python 依賴。manage.sh會一併裝好其系統依賴 (按發行版命名差異自動解析)。下載源可用CLOAKBROWSER_DOWNLOAD_URL覆蓋;ZCODE_CAPTCHA_BROWSER_BIN可指向任意已有瀏覽器。實測部分發行版自帶的 Chromium(如 Debian 13)會被風控拒絕——自動下載的補丁二進制即為此問題的內建解法。
⚠️ 放在反向代理後時注意:後台登入失敗限速以RemoteAddr為鍵,不信任X-Forwarded-For(防偽造),因此反代後所有客戶端會共用同一失敗桶 (5 分鐘 10 次即整站 429)。解法:以--host 127.0.0.1安裝,讓服務只監聽 回環、僅由本機反代轉發,詳見deploy/README.md。
核心項(全部見 internal/config/config.go):
| 變量 | 默認 | 說明 |
|---|---|---|
ZCODE_PORT / ZCODE_HOST |
3000 / 0.0.0.0 | 監聽地址 |
ZCODE_DATA_DIR |
./data |
賬號庫、密鑰、設備指紋 |
ZCODE_CAPTCHA_BROWSER |
false | 啟用 rod 瀏覽器池自動求解 |
ZCODE_CAPTCHA_BROWSER_BIN |
自動發現 | Chromium 二進制路徑 |
ZCODE_ASYNC_ENABLED |
true | 掛載 /async/v1/messages 空閒池 |
訪客提交的邀請碼存於數據庫(後台「設置」頁可改),不走環境變量。
賬號配置 proxy_url 後,該賬號的網關請求、額度查詢與套餐領取均走對應代理;
支持 http(s)://(CONNECT)與 socks4://、socks5://、socks5h://(socks5h
由代理解析域名)。代理無效時回退直連並記錄 last_error。
JWT 賬號入池(批量添加 / OAuth / CLI login)後自動:激活事件上報 →
billing/preview 按優先級逐個 billing/claim(驗證碼 3007 自動換碼重試一次)。
後台賬號頁另有「領取套餐」按鈕(工具欄全量 + JWT 賬號行內單賬號)。
go build ./... && go vet ./... && go test ./... # 全量驗證
go test -race ./... # 併發檢查(需 C 工具鏈)- 推
v*tag → GitHub Actions 自動交叉編譯 Linux 產物(linux/amd64、linux/arm64) 並上傳 Releases。僅維護這兩個平台:本項目面向服務端自部署。 - 前端改動:
cd frontend && npm install && npm run build,把更新後的frontend/dist一併提交(dist已入庫並由go:embed打包;改版後要刪掉舊的 hash 檔)。 - 行為契約與里程碑台账見
PLAN.md(唯一權威,含逐項驗收狀態)。
deploy/manage.sh的 systemd 模板有兩份:deploy/zcode2api.service與腳本內write_unit()的 heredoc(單獨下載腳本時走後者)。改模板時兩處都要改。- 部署腳本必須保持 LF:
.gitattributes已對*.sh/*.service強制eol=lf, 改動後用git ls-files --eol deploy/確認索引為i/lf;可執行位用git update-index --chmod=+x設定(Windows 檔案系統不保留該位)。 .env不會被自動載入:專案未引入 dotenv,manage.sh產生的.env由 systemd 的EnvironmentFile讀取;本機直接跑二進制時需自行 source。frontend/dist的 embed 宣告必須在倉庫根包(webui.go):go:embed只能引用 宣告檔所在目錄樹內的文件,internal/web無法引用它。- 上游回應形態:zcode.z.ai 的非流式回應是標準 Anthropic Messages 頂層形態
(
id/content/stop_reason/usage都在頂層,沒有嵌套message物件)。 權威依據見internal/gateway/usage.go頭部註釋。 - 測試隔離:一律
config.DBPath = filepath.Join(t.TempDir(), "accounts.db"); captcha 測試用SetSolver(假求解器)+SetConfigProvider(固定配置),否則會打真實 上游;e2e 帳號用 api_key 模式(憑證不含兩個點)即不觸發驗證碼路徑,離線穩定。
管理員在後台「設置」頁填寫邀請碼後,/guest 頁面即對外開放(清空邀請碼
即關閉)。訪客的提交路徑刻意比後台窄:
在後台「設置」頁填入 Cap 後台給出的三個值即啟用:
| 欄位 | 取自 Cap 後台 | 範例 |
|---|---|---|
| 實例地址 | 你的 Cap 部署地址(不含 site key) | https://cap.example.com |
| Site Key | 建立 site key 後的識別碼 | d9256640cb53 |
| 密鑰 | secret key(不是管理員 ADMIN_KEY) | — |
實際呼叫地址為 {實例地址}/{Site Key}/,設定頁會即時顯示拼出的結果供核對。
-
三項都填才啟用;只填部分會被拒絕儲存(避免留下半殘配置)。 三項皆留空即停用。
-
密鑰只留在服務端,絕不下發瀏覽器;拼好的地址會回顯給前端(widget 需靠它取題)。
-
Site Key 填錯時返回 502(路徑不存在屬配置問題),而非報成「驗證未通過」。
-
兩步各驗一次:Cap token 是一次性的,第一步用過即失效,第二步會自動重新求解。
-
未配置時不渲染驗證元件、後端也跳過校驗——自建實例位址因部署而異,無法給預設值。
-
Cap 服務不可達時返回 502(管理員要查配置),而非報成「驗證未通過」誤導訪客。
-
只走 OAuth 授權,不提供令牌輸入框。完成授權能證明提交者確實持有該帳號; 貼上一串 JWT 什麼都證明不了。
-
實測通過才入池。授權只說明「現在持有」,不說明「當下可用」——帳號可能已 被封、額度耗盡或地區受限。後端會用該憑證發起一次最小的真實請求 (
max_tokens=1),成功才寫入賬號池;失敗直接丟棄。 -
不回顯任何帳號信息。回應只有成功與否,不含 ID、郵箱、額度或賬號列表。
-
邀請碼 + 每 IP 每日 3 次。配額在開始授權時扣減;未設邀請碼時入口關閉 (fail closed)而非開放。
-
可選人機驗證。接入自建 Cap 實例後,兩步各驗一次 (Cap token 一次性,第二步需重新求解)。未配置時整段跳過。
⚠️ 實測需要驗證碼求解器,因此訪客提交要求ZCODE_CAPTCHA_BROWSER=true; 未啟用時提交會因驗證碼不可用而失敗。
不再需要調用的賬號可「歸檔」:歸檔即強制停用並從賬號池隱藏,僅在後台歸檔區 保留記錄(累計用量可查);歸檔賬號不參與調度、套餐領取與額度刷新,恢復後 保持停用狀態,需手動啟用才會重新入池。
AGPL-3.0(見 LICENSE),僅供學習研究與個人自部署使用;使用本項目產生的 一切行為與後果由使用者自行承擔,請自行遵守上游服務條款。本項目與 Z.AI 無任何關聯。