第七章：部署與維運

7.1 目前部署架構

概覽

本系統以 Claude Code CLI 為核心執行環境，直接部署於 JP VPS 的 /home/ubuntu 用戶空間，不使用獨立容器包裝 Claude Code 本身。

用戶 / 觸發者
      |
      v
JP VPS (主機名稱已遮蔽)
      |
      +-- /home/ubuntu/.claude/        ← Claude Code 執行環境
      |       +-- agents/              ← 39 位 Agent 定義
      |       +-- skills/              ← 核心 skill 定義（brand-research, marketing, research 等）
      |       +-- hooks/               ← 品質閘門與 lifecycle 事件 hook
      |       +-- logs/                ← 執行日誌（月份 JSONL）
      |       +-- library/             ← 知識庫與參考資料
      |
      +-- /home/ubuntu/.claude/projects/   ← 專案工作目錄
              +-- ceo-high-level-insights/ ← 本專案

主機規格

項目	值
主機名	[主機名稱已遮蔽]
位置	日本 Tokyo
Tailscale IP	[Tailscale IP 已遮蔽]
公網 IP	[公網 IP 已遮蔽]
OS	Ubuntu 24.04.4 LTS (aarch64 ARM64)
CPU	4 核心
RAM	23 GB（目前使用約 30%）
Disk	193 GB（目前使用約 39%，74 GB）
Swap	4 GB（目前使用約 65%，2.6 GB；建議關注）

部署模型特徵

無常駐服務：Claude Code CLI 按需呼叫，不作為背景 daemon 運行
無藍綠環境：技術原因是 CLI 工具本身無 "版本切換" 需求；升級路徑為直接更新 CLI 版本
單機單用戶：目前所有 AI 工作流均由 ubuntu 用戶執行
Tailscale 隔離：管理界面與工具均透過 Tailscale 私網存取，不對公網開放

7.2 依賴項目

核心依賴

依賴	版本	用途	若失效的影響
Claude Code CLI	2.1.71	主執行環境	全部 AI 工作流停止
Anthropic API	—	模型呼叫	全部 AI 工作流停止
Node.js	22.22.1	Claude Code 執行時期	CLI 無法啟動
git	系統版	版控、事實來源	無法 commit / 追溯變更
jq	系統版	Hook 日誌解析	Runtime event log 靜默失敗（`exit 0`，不影響主流程）
python3	系統版	Hook transcript 解析	Skill / mode 欄位缺失，但事件本身仍記錄

MCP Plugin 依賴

Plugin	用途	啟用方式
context7 (`@upstash/context7-mcp`)	文件查詢 / 技術參考	npx 按需啟動
claude-mem	跨 session 觀察索引注入	SessionStart hook 自動觸發

MCP plugin 透過 npx 動態拉取；若 npm registry 不可用，context7 會失效，但不影響 Claude Code 本身運行。claude-mem 失效只影響 SessionStart 的觀察索引注入，不影響 skill 執行。

外部服務依賴

服務	性質	備用方案
Anthropic API	必要，無備援	等待 Anthropic 恢復；關注 https://status.anthropic.com
NAS 備份裝置 [IP 已遮蔽]	restic 備份目標	Google Drive 雲端同步為第二層
Tailscale	內網連線	SSH 公網 IP [已遮蔽] 作為緊急備用

7.3 日常維運

/ops Skill

/ops 是內建的維運 skill，可在 Claude Code 互動中直接呼叫：

指令	功能	注意事項
`/ops status`	顯示磁碟、記憶體、容器狀態	快速健康檢查，無副作用
`/ops cleanup`	Journal 清理 + Docker 空間報告	會刪除舊 journal；確認無活躍故障調查再執行
`/ops logs <容器名>`	查看容器最近 50 行日誌	常用：n8n, traefik, pangolin
`/ops update`	`apt update && apt upgrade`	可能觸發 Docker daemon 重啟，見 7.3.3

Hooks 自動化

Claude Code lifecycle hooks 位於 ~/.claude/hooks/：

Hook 時機	腳本	功能
SessionStart	—	校正 `~/CLAUDE.md` symlink；注入 claude-mem 觀察索引
PostToolUse	`runtime-event-log.sh`	記錄 skill 執行、subagent 事件到月份 JSONL
SubagentStop	`runtime-event-log.sh`	記錄 subagent 結果（completed / blocked）
ConfigChange	`runtime-event-log.sh`	記錄設定變更事件

runtime-event-log.sh 寫入路徑：~/.claude/logs/YYYY-MM.jsonl

重要設計：

若 jq 不存在，腳本 exit 0（靜默跳過），不中斷主流程
Transcript 解析結果有 file-based cache（~/.claude/logs/.runtime-meta-cache/），避免重複 parse 大型 JSONL

Log Rotation

日誌類型	路徑	策略
Claude Code runtime events	`~/.claude/logs/YYYY-MM.jsonl`	按月自動換檔；舊檔不自動刪除，需手動清理
System journal	`journald`	已限制 100MB：`sudo journalctl --vacuum-size=100M`
Docker 容器日誌	Docker 預設	未設定 max-size；若容器長期高頻輸出，建議補充 log driver 限制

維運週期建議：

每月：確認 ~/.claude/logs/ 未超過 50MB 閾值（du -sh ~/.claude/logs/）
每季：清理超過 6 個月的月份 JSONL（目前無自動清理機制）

7.4 成本結構

API Token 消耗

三組核心 skill 的 token 消耗倍數（以基準線 1x 計算）：

Skill	倍數	說明
research	2.2x	標準研究流程；單階段 agent dispatch
brand-research	2.3x	品牌研究；結構略複雜，多一組 context 解析
marketing	4.6x	行銷文案；最貴，因多階段 agent dispatch

marketing 4.6x 的含義：同樣一次用戶呼叫，/marketing 在內部會觸發多個 subagent（如 strategy agent、copywriter agent），每個 subagent 均產生獨立 API 往返。若需控制成本，首要考慮精簡 marketing skill 的 agent dispatch 階段數（歸入 roadmap 路線 B）。

brand-research 2.3x 的含義：相對 research 的 2.2x 僅多 0.1x，主要因品牌分析增加了結構化 context 解析步驟。成本合理，優先級較低。

成本管理原則

每組 eval 目前只有 1 run baseline；protocol 要求結構級變更需 3-run window，不要為了省 token 跳過
多 subagent dispatch 的 skill（如 marketing）在大量批次使用前，需先確認 API rate limit 餘量
claude-mem SessionStart 注入約 25 筆觀察索引，是每次 session 的固定起始開銷

VPS 費用

JP VPS 為 Oracle Cloud Always Free Tier（ARM64 VM）。目前無直接 VPS 費用，但需注意：

Oracle 保留調整 Always Free 政策的權利
NAS 備份裝置為本地設備，無月費
Google Drive 同步使用個人帳號容量，目前未超過免費額度

7.5 監控與告警

Runtime Event Log

主要監控工具：~/.claude/logs/YYYY-MM.jsonl

每筆記錄包含以下欄位：

{
  "date": "2026-03-10",
  "timestamp": "2026-03-10T14:00:00Z",
  "type": "subagent-stop",        // 事件類型
  "session_id": "...",
  "skill": "brand-research",      // 觸發的 skill
  "mode": "full",                 // 執行模式
  "agent": "BrandResearchAgent",  // subagent 名稱
  "model": "claude-sonnet-4-6",   // 實際使用模型
  "result": "completed",          // completed / blocked / null
  "blocked_reason": null          // rate_limit / auth / unknown
}

查詢方式（需 jq）：

# 今日所有 skill 執行
jq 'select(.date == "2026-03-10")' ~/.claude/logs/2026-03.jsonl

# 找出所有 blocked 事件
jq 'select(.result == "blocked")' ~/.claude/logs/2026-03.jsonl

# 統計各 skill 使用次數
jq -r '.skill // "null"' ~/.claude/logs/2026-03.jsonl | sort | uniq -c | sort -rn

# rate_limit 事件
jq 'select(.blocked_reason == "rate_limit")' ~/.claude/logs/2026-03.jsonl

Telemetry Review Window（Roadmap 5.1）

目前 roadmap 5.1 為進行中（🔄）狀態：

驗收條件：累積至少 10 次核心 skill run 後做一次 monthly review
審視項目：InstructionsLoaded / SubagentStart / SubagentStop / ConfigChange 的噪音比例、缺欄位比例、查詢可用性
健康閾值：

指標	正常範圍	異常處置
`~/.claude/logs/` 大小	< 50MB	檢查是否有失控的 lifecycle 或 eval 寫入
plugin-excluded CLAUDE.md 數量	≤ 20	確認是否為目錄層級擴張
blocked_reason = rate_limit 事件	偶發	若單日 > 5 次，需調整呼叫頻率或確認 API 配額

現有基礎設施監控

以下為 JP VPS 上現有的監控工具（與 AI 工作流分離）：

工具	URL	用途
Backup Status	http://[TAILSCALE-IP]:9898	restic 備份狀態（每小時更新）
Homarr	http://[TAILSCALE-IP]:7575	服務儀表板（容器狀態概覽）
Portainer	https://[TAILSCALE-IP]:9443	Docker 容器管理

以上服務均僅限 Tailscale 私網存取。

告警缺口（現況）

目前沒有自動告警機制覆蓋以下場景，需人工定期檢查：

Anthropic API 不可用（無 uptime monitor）
~/.claude/logs/ 超過大小閾值（無自動通知）
Claude Code CLI 版本過舊（無自動版本檢查）

若未來需補齊，建議優先透過 n8n 建立簡單 HTTP 健康檢查 + Telegram / Discord 通知，複用現有 n8n 工作流程基礎設施。

7.6 災難復原

Git Repo 備份

所有 ~/.claude/ 目錄（含 skills、agents、hooks、logs、library、projects）均包含在 JP 的 restic 備份範圍內：

備份路徑：/home/ubuntu（含 .claude/ 子目錄）
備份目標：sftp://[NAS-HOST]:/backup/[VPS-NAME]
排程：每日 20:00（user）+ 04:00（root 代跑）
保留策略：每日 7 份 / 每週 4 份 / 每月 6 份

此外，~/.claude/projects/ 下的各專案本身是 git repo，透過 git push 可保有獨立遠端備份（目前是否有 remote 需確認）。

設定檔版控

以下設定檔均受 git 版控或 restic 備份保護：

檔案/目錄	保護方式
`~/.claude/skills/*/SKILL.md`	git（`~/.claude/` 為 tracked repo）
`~/.claude/agents/REGISTRY.md`	git
`~/.claude/hooks/*.sh`	git
`~/.claude/docs/*.md`	git
`~/CLAUDE.md`（symlink source：`~/.claude/workspace.md`）	git
Claude Code CLI 本身	restic 備份 `/home/ubuntu`
Node.js 環境	需重新安裝（非備份範圍）

還原流程

情境 A：單檔/設定誤刪

# 從 git 還原
cd ~/.claude
git log --oneline -10
git checkout <commit-hash> -- skills/brand-research/SKILL.md

情境 B：VPS 全毀，需重建

準備新 Ubuntu 24.04 主機，安裝 restic、Docker、Tailscale、Node.js 22.x
設定 SSH 金鑰，取得 restic 密碼（~/.restic-password）

還原 user-space：

export RESTIC_REPOSITORY="sftp:[USER]@[NAS-IP]:/backup/[VPS-NAME]"
sudo restic restore latest --target / --password-file ~/.restic-password

還原 Docker volumes 與 system state：

sudo /home/ubuntu/bin/restore-backup.sh --target-root / --force-volumes

校正 workspace symlink：確認 ~/CLAUDE.md 指向 ~/.claude/workspace.md
確認 Claude Code CLI 版本（claude --version）；若版本不對，重新安裝
重啟容器服務：
```
cd /home/ubuntu && docker compose up -d
```

RTO / RPO 估計

指標	估計值	說明
RPO（資料遺失上限）	最多 8 小時	兩次備份排程間距（04:00 + 20:00）
RTO（服務恢復時間）	2-4 小時	取決於新主機準備時間
設定檔 RPO	以 git commit 為單位	只要有 push，可精準還原

7.7 擴展考量

多人使用

目前架構為單用戶（ubuntu）單機設計。若需支援多人同時使用：

主要障礙：

~/.claude/ 是用戶層設定，多人共用會互相覆蓋 CLAUDE.md 與 memory
git log 無法區分哪位操作者執行了哪次 skill run
API key 共用會讓 rate limit 更快耗盡

建議方案（依成本排序）：

最小可行：每位用戶建立獨立 Linux 用戶帳號，各自有獨立 ~/.claude/ 目錄；透過 Ansible 統一同步 skills/agents 定義
中期：抽出共享 skill 定義到 /opt/claude-shared/，各用戶帳號透過 symlink 引用；log 集中到共享目錄
長期：若使用者超過 5 人，考慮評估 Claude Code 的 enterprise/team 方案

多專案並行

目前 ~/.claude/projects/ 下有多個專案並行，設計上是安全的（各專案獨立目錄，互不干擾）。需注意：

若同時執行多個 heavy skill（如 marketing），API token 消耗會疊加，容易觸碰 rate limit
~/.claude/logs/YYYY-MM.jsonl 是所有專案共用的單一月份日誌，大量並行執行時可能有寫入競爭（目前 >> append 為 shell 層級，非 atomic write）

建議：若需大量並行，考慮在日誌寫入前加鎖，或改為按專案分開 log 目錄。

API Rate Limits

Anthropic API 限制依方案而異。目前無自動 rate limit 監控，blocked 事件僅透過 runtime-event-log.sh 被動記錄。

預防措施：

marketing skill（4.6x token）避免在短時間內批次呼叫
若單日 blocked_reason = rate_limit 事件 > 5 次，應暫停批次作業並確認帳號配額
必要時可透過 Anthropic 控制台確認用量：https://console.anthropic.com/usage

未來可改進：在 skill 層加入指數退避重試（exponential backoff），或在 n8n 工作流排程器中加入 rate limit 預算控制。

附錄：快速參考指令

# 系統健康快速檢查
df -h / && free -h && docker ps --format "table {{.Names}}\t{{.Status}}"

# Claude Code runtime log 查看（今月）
cat ~/.claude/logs/$(date +%Y-%m).jsonl | jq -r '[.date, .type, .skill, .result] | @tsv'

# 檢查 blocked 事件
jq 'select(.result == "blocked")' ~/.claude/logs/$(date +%Y-%m).jsonl

# logs 大小檢查（閾值 50MB）
du -sh ~/.claude/logs/

# 備份狀態檢查
~/bin/backup.sh --preflight

# Ansible 全機健康確認
cd ~/infra && ansible all -m ping

# Docker socket consumer refresh（每週日系統更新後需確認）
~/bin/refresh-docker-socket-consumers.sh

本章節依據 ~/VPS-ALL.md（2026-03-08）、~/.claude/docs/roadmap.md（2026-03-09）、~/.claude/hooks/runtime-event-log.sh、~/.claude/skills/ops/SKILL.md 及 ~/.claude/docs/memory.md 撰寫。