docs(readme): self-hosted 快速開始改成完整流程（CF 註冊 → 裝 wrangler/acr → init 全自動）
- 步驟 1-4：申請 CF 帳號（含找 Account ID / 建 API Token 三權限表）→ 裝 wrangler → 裝 acr → acr init --self-hosted - 附 init 實際輸出畫面（建 KV → 下載 wasm → 部署 19 Worker → seed recipe） - 強調：用戶不需懂 git/tinygo，預編譯 wasm 從 GitHub 拉、用自己的 CF token 部署到自己帳號 - 最後手動 wrangler secret put ENCRYPTION_KEY（誠實標不自動化） - CLI 指令表加 acr update Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -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: <recipe 名>` 或 `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 <service> 取得 credentials.yaml 範本 + workflow 範例
|
||||
acr list 列出已部署的 workflow
|
||||
acr logs <name> 查看執行記錄
|
||||
acr update self-hosted：拉新版零件/引擎並重新部署到你的 CF
|
||||
```
|
||||
|
||||
> 給 AI 操盤手：開始前讀 `.claude/rules/06-mindset.md`（或 arcrun-mindset Skill）——它說明 arcrun 的世界觀（工作流是 default、零件稀有且不自製、一切外部 API 皆 recipe），讓你一開始就走在正路上。
|
||||
|
||||
Reference in New Issue
Block a user