diff --git a/README.md b/README.md index ca53544..769cf69 100644 --- a/README.md +++ b/README.md @@ -57,24 +57,83 @@ arcrun 只有兩種東西,分清楚就不會做歪: ## 快速開始(Self-hosted) -arcrun 是 self-hosted 開源:你用自己的 Cloudflare 帳號跑整套。一次裝好,之後就是你的。 +arcrun 是 self-hosted 開源:你用**自己的** Cloudflare 帳號跑整套。一次裝好,之後就是你的,不依賴任何人的服務。 -### 1. 取得 Cloudflare 憑證 +你總共只需要做 4 件事(步驟 1-4),其餘 CLI 自動完成、你只是看著機器跑。 -你需要一個 CF 帳號,並在 dashboard 建一個 **API Token**(權限:Workers Scripts Edit + KV Storage Edit + Workers R2 Storage Edit)。CLI 不代管你的憑證——你自己建、自己持有。 +### 1. 申請 Cloudflare 帳號(免費) -### 2. 一鍵初始化 +到 [dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up) 註冊。免費方案(Workers free tier)就足夠跑起來。 + +註冊後你需要兩個東西——**Account ID** 和 **API Token**: + +**Account ID**:登入後在 [dash.cloudflare.com](https://dash.cloudflare.com) 隨便進一個區段,網址列會是 `dash.cloudflare.com/<這串就是 Account ID>`;或在右側欄 "Account ID" 直接複製。 + +**API Token**:到 [My Profile → API Tokens](https://dash.cloudflare.com/profile/api-tokens) → **Create Token** → **Create Custom Token**,給以下權限(CLI 用它建 KV / 部署 Worker): + +| 類型 | 項目 | 權限 | +|---|---|---| +| Account | Workers Scripts | Edit | +| Account | Workers KV Storage | Edit | +| Account | Workers R2 Storage | Edit | + +建好後**複製那串 token**(只會顯示一次)。CLI 不代管你的憑證——你自己建、自己持有。 + +### 2. 安裝 Cloudflare CLI(wrangler) + +CLI 部署 Worker 時會用到 wrangler。先裝它: + +```bash +npm i -g wrangler +``` + +### 3. 安裝 arcrun CLI ```bash npm i -g arcrun +``` + +### 4. 一鍵初始化(其餘全自動) + +```bash acr init --self-hosted ``` -貼上 CF Account ID + API Token,CLI 自動:建立所需 KV、部署所有 Worker(含執行引擎 cypher-executor 與全部零件)、啟用 workers.dev、寫回設定。跑完會提示你手動設定 runtime secret(如 `ENCRYPTION_KEY`),這一步刻意不自動化(secret 不進工具流程)。 +CLI 會問你 **Account ID** 和 **API Token**(步驟 1 取得的),貼上後它自動完成: -> 想先不碰 Cloudflare、純在本機感受語法?`acr init --local` 然後 `acr run`。 +``` +→ 驗證 Cloudflare 憑證... ✓ +→ KV WEBHOOKS... ✓ (建 7 個 KV namespace,已存在則重用) +→ R2 WASM_BUCKET... ✓ +→ workers.dev subdomain: your-account +→ 下載部署物 + 部署 Worker(從 GitHub 拉預編譯 wasm,用你的 CF token 部署)... + ✓ 部署完成:19 個 Worker 全部成功 +→ seed 10 個 API recipe... ✓ +✓ Cloudflare 資源就緒(7 KV + R2) +✓ 設定寫入 ~/.arcrun/config.yaml +``` -### 3. 寫一個工作流 +你不需要懂 git、不需要懂 tinygo、不需要手動建任何東西——預編譯好的零件(`.wasm`)直接從 GitHub 下載,用**你自己的** CF token 部署到**你的**帳號。 + +**最後一步(手動,CLI 會印提示)**:設定加密金鑰 secret。這一步刻意不自動化(密鑰不進工具流程): + +```bash +# CLI 會印出確切指令,照貼即可。三個 Worker 共用同一把 key: +wrangler secret put ENCRYPTION_KEY --name arcrun-cypher-executor +wrangler secret put ENCRYPTION_KEY --name arcrun-auth-static-key +wrangler secret put ENCRYPTION_KEY --name arcrun-auth-service-account +# 生成一把 key:node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" +``` + +完成。之後有新版零件,跑 `acr update` 一樣自動拉新、重部署。 + +> 想先不碰 Cloudflare、純在本機感受語法?`acr init --local` 然後直接跳到下面「寫一個工作流」。 + +--- + +## 裝好之後:開始用 + +### 寫一個工作流 `hello.yaml`: @@ -92,7 +151,7 @@ config: acr run hello --input input="Hello, world" # → HELLO WORLD ``` -### 4. 要打外部 API?寫一個 recipe(不是做零件) +### 要打外部 API?寫一個 recipe(不是做零件) ```bash # 上傳一個打外部 API 的 recipe(push 時會幫你檢查打不打得通) @@ -101,7 +160,7 @@ acr recipe push my_api_recipe.yaml recipe 裡寫好 endpoint / method / body 模板,credential 由 auth 自動注入。workflow 裡用 `component: ` 或 `component: rec_xxxx` 引用它。 -### 5. 上傳 credential(client 端加密,明文不離開你的機器) +### 上傳 credential(client 端加密,明文不離開你的機器) ```bash acr auth-recipe list # 看支援哪些服務的認證 @@ -109,7 +168,7 @@ acr auth-recipe scaffold notion # 取得 credentials.yaml 範本 acr creds push credentials.yaml # AES-GCM 加密後上傳到你自己的 KV ``` -### 6. 部署 + 觸發 +### 部署 + 觸發 ```bash acr push newsletter.yaml # 部署,取得 Webhook URL @@ -173,6 +232,7 @@ acr auth-recipe list 列出支援的第三方服務認證 acr auth-recipe scaffold 取得 credentials.yaml 範本 + workflow 範例 acr list 列出已部署的 workflow acr logs 查看執行記錄 +acr update self-hosted:拉新版零件/引擎並重新部署到你的 CF ``` > 給 AI 操盤手:開始前讀 `.claude/rules/06-mindset.md`(或 arcrun-mindset Skill)——它說明 arcrun 的世界觀(工作流是 default、零件稀有且不自製、一切外部 API 皆 recipe),讓你一開始就走在正路上。