Appearance
知識庫索引
最後更新：2026-06-05 文章總數：87
本索引是整個知識庫的入口點。所有概念文章在此列出，按主題分類並附簡短摘要。
目錄
依主題分類
Claude Code / AI 輔助開發
- Claude Code 權限模式與安全設定 — 六種權限模式（default / acceptEdits / plan / auto / dontAsk / bypassPermissions）的行為差異、切換方式、危險指令禁用清單（denyList）設定、Status Line 工具，以及搭配 Superpowers 的推薦組合
- Claude Code Dev Container 導入 — Claude Code 在 Docker 容器內的隔離執行：filesystem/network isolation 縮小爆破半徑、WSL2 + Docker Engine 設定、devcontainer.json 範例（Python 3.13 + Node 22 + uv）
- CLAUDE.md 最佳實踐：12 條規則 — 透過精簡行為規則（不超過 200 行）關閉 Claude 已知失敗模式：Karpathy 原始 4 條 + 補充 8 條，涵蓋 Token 預算、衝突處理、測試品質、靜默失敗等場景；測試數據顯示錯誤率從 41% 降至 3%
- OpenSpec SDD 框架 — Spec-Driven Development 框架：explore（Thinking Phase）→ propose → apply → verify → archive 核心工作流、四個 artifact（proposal/specs/design/tasks）、與 Superpowers 的整合方式；含 AI 輔助完善 config.yaml 的 Prompt
- OpenSpec 導入現有專案（Brownfield 指南） — 將 OpenSpec 整合至已存在專案的三個 Phase：CLI 初始化、AI 輔助 spec 回填、格式驗證，含 config.yaml 模板
- GitHub Copilot Sub-Agent 編排 — Coordinator/Worker 模式進行 context 隔離的 AI 輔助開發，搭配 OpenSpec 完成從需求到歸檔的完整流程
- Superpowers AI 開發方法論 — 強制性 AI 開發工作流框架：TDD、subagent 隔離、No Placeholders 計畫規則、兩階段 code review；與 OpenSpec 的能力對比及完整整合流程
- Harness Code Review SOP — 以 Harness 在 Claude Code 建立六視角平行 Code Review 團隊（架構/安全/效能/風格/測試/前後端邊界），支援修正後 Re-review 迴圈
- Repomix — 程式庫打包為 AI 輸入素材 — 將整個程式庫打包成單一 AI 友善檔案：npx 免安裝執行、Glob/stdin/remote 三種打包模式、git log/diff 附加、--compress 壓縮選項
- Claude Design — Codebase Input 方式比較 — Repomix XML 上傳 vs 原生 Repo 連結的場景選擇：Design System 建立用原生連結、單次 Prototype 迭代用 Repomix XML；含各框架打包指令（Next.js / shadcn/ui / monorepo）
AI 工具整合（MCP / Microsoft 365）
- M365 MCP Server（Kubernetes 部署） — FastMCP v3 + Azure Entra ID OAuth 2.1 的 remote MCP Server：send_mail / get_my_profile、Docker Compose 本地開發、AKS 部署、環境變數與端點完整參考
- Azure App Registration — M365 MCP Server SOP — Azure AD App Registration 的逐步 SOP：Client Secret、Redirect URI、mcp-access scope、Graph API 委任權限、Admin Consent、Token Version
- MCP OAuth Well-Known Subpath 的 nginx Ingress 架構 — Subpath 部署的 3 Ingress 模式：解決 FastMCP well-known 路徑不一致 + nginx per-Ingress rewrite 限制；含 Claude Desktop Connector vs mcp-remote 方案比較
- Claude Desktop Extension（MCPB）打包與發布 — local Python MCP server 打包為 .mcpb：manifest.json schema、uv 執行器、Allowlist 分發、常見錯誤（hatchling 打包目錄、tools parameters、manifest_version）
- Azure Graph API 驗證與呼叫 — ROPC 流程取得 Access Token 並呼叫 Microsoft Graph API，含實際 Tenant ID / Client ID 參數與常用 API 端點
Python 開發
- Python 3.15 Explicit Lazy Imports（PEP 810） —
lazysoft keyword 將 import 延後到首次存取：2–3 倍 CLI 啟動加速、自適應特化後零 overhead；PEP 690 被拒到 PEP 810 通過的設計歷程、避坑要點（副作用模組、registry pattern）與升級準備 SOP - Loguru + Redis 集中日誌 — Loguru Callback Sink 將微服務日誌結構化後寫入 Redis List（
logs:{service}:{date}），無需 ELK 即可跨容器集中查詢；redis_sink 完整實作、TTL 設計、消費端查詢指令
Windows 開發環境
- WSL 2 安裝指南（Windows 11） — WSL 2 + Ubuntu 安裝至非系統碟（--location）、export/import 搬移法、wsl.conf 建議設定、啟動目錄修正
- Linux 剪貼簿工具（xclip / xsel / wl-copy） — 在 Linux / WSL2 終端機將長字串或檔案內容複製到系統剪貼簿，X11 / Wayland / macOS 工具對照
- uv Python 版本與環境管理 — 以 uv 取代 pip+venv+pyenv：Python 版本安裝、--default vs pin 差異、虛擬環境、依賴鎖定（uv.lock）、協作者一鍵還原
- PowerShell Terminal 美化指南 — Windows Terminal + PowerShell 7 美化與增強：Oh My Posh、Nerd Font、PSReadLine、Terminal-Icons、VS Code 終端一致化
- PowerShell HTTPS Proxy 設定 — 五種 Proxy 設定方式（Session 環境變數到 WinHTTP 系統層級）、proxy-on/off 快捷函式範本
- WSL2 Terminal 美化與功能強化 — WSL2 Ubuntu shell 強化：Zsh、Oh My Zsh、Powerlevel10k、插件組合與 zoxide 目錄跳轉
- Volta Node.js 版本管理 — 自動切換 Node 版本與專案 pin 機制：全域預設、package.json volta 欄位、npm/yarn 行為差異
- WSL 環境設定進階技巧 — WSL 與 Windows 環境整合的兩大常見問題：PATH 汙染過濾（/mnt/c/ 路徑）與 DNS 解析失敗修復（generateResolvConf）
- 企業環境 Node.js SSL 憑證錯誤修復 — Zscaler 等 TLS inspection 環境下設定
NODE_EXTRA_CA_CERTS，含 Windows PowerShell / WSL 雙環境步驟與常見踩坑 - lnav — 日誌檢視工具 — 互動式 CLI 日誌導覽器的 Dockerfile 安裝模式：靜態執行檔下載、映像層清理、night-owl 主題設定
- Windows 效能分析：WPR + WPA + xperf — ETW 技術錄製系統 trace（WPR）、xperf CLI 匯出 DPC/ISR 與 CPU 報告供 AI 分析、WPA 圖形化定位卡頓驅動；含常見錯誤碼（0xc5585011 / 0x800704c7）排除
- Locale Emulator + Steam 整合（日系遊戲轉區） — 透過 PowerShell + ps2exe 將日系遊戲包裝成 .exe 加入 Steam：LEProc.exe 啟動、UTF-8 with BOM 編碼、Steam 非 Steam 遊戲設定與遊玩時間追蹤
Kubernetes 維運
- Kubernetes RBAC 帳號管理 — 兩種受限 ServiceAccount kubeconfig：Power User（全域維運禁刪 Node/Namespace）與 Restricted（特定 Namespace 僅讀 Pod Log），含憑證輪替 SOP
- KEDA（Kubernetes Event-Driven Autoscaling） — 基於外部事件（Queue 深度、Prometheus 指標等）自動擴縮 Pods，支援 scale-to-zero，Helm 安裝
- Kubernetes HPA 水平自動擴縮 — 原生 autoscaling/v2 HPA：CPU/Memory 使用率觸發、多指標同時判斷、resources.requests 必要前提，以及與 KEDA 的比較
- Kubernetes VolumeSnapshot 磁碟快照 — Azure Disk 三步驟快照 SOP：VolumeSnapshotClass → VolumeSnapshot → 從快照還原 PVC
- Kubernetes Pod Anti-Affinity 與 Deployment 策略 — Pod 反親和性確保副本跨節點分散（硬性 vs. 軟性限制）、ReadWriteOnce PVC 搭配 Recreate 策略解決滾動更新衝突
- Kubernetes 維運技巧速查 — 日常維運速查手冊：跨 Namespace DNS、envFrom 注入、kubeconfig 管理、NFS Provisioner、Internal LB、PVC fsGroup、kubectl cp、emptyDir
- Kubernetes Python Client 操作指南 — 官方 kubernetes Python 套件：kubeconfig 載入、kubectl proxy / Bearer Token 遠端存取、ServiceAccount RBAC、SSL 憑證驗證、Watch 事件監聽與斷線重連
- Kubernetes Pod Anti-Affinity 與 Deployment Strategy — Pod 反親和性將副本分散至不同節點（required vs preferred）；Recreate 策略解決 ReadWriteOnce PVC 掛載衝突
- 驗證 Base64 Kubeconfig 有效性 — 不覆蓋
~/.kube/config的前提下驗證 Base64 kubeconfig 連線能力：四步驟 SOP、常見錯誤判讀、憑證到期日檢查
高可用性與儲存
- DRBD Split-Brain 修復（Pacemaker HA Cluster） — Split-Brain 診斷與 --discard-my-data 修復、colocation score 防回流修正、nfs_ip findif 修復、同步後 7 步恢復 SOP
- DRBD + Pacemaker NFS HA Cluster 完整復原 Runbook — 全場景復原手冊：症狀診斷 Decision Tree、6 大 Scenario（is-managed=false / group 出錯 / 無 promotion score / 單節點存活 / RA 失敗 / split-brain）、日常維護 Checklist、Tech Debt 改進建議
- NFS Client Mount 疑難排解與最佳實踐 — Linux host 作為 NFS client 的完整排查：mount 驗證四維度、fstab 選項深度解析（_netdev / nofail / timeo / retrans）、umount+mount 正確流程、HA failover 期間行為
代理與網路服務
- Squid Proxy（Kubernetes 部署） — Squid 正向代理的 K8s 部署：ACL 存取控制、快取策略、Azure Internal LoadBalancer 暴露
- Shadowsocks Sidecar 代理 — 以 Sidecar 模式部署 Shadowsocks SOCKS5 代理，ss-server + ss-local 架構設計
資料庫
- MariaDB Helm 部署（Kubernetes） — Bitnami Helm Chart 部署 MariaDB：Standalone 與 Galera 多 Master 架構、TLS 憑證、InnoDB 性能調優
- PostgreSQL Group Role Ownership 管理 — Group Role Pattern 解決多人共用 DB 的 ownership 問題：REASSIGN OWNED 批次轉移、ALTER ROLE SET role 防止復發、完整 SQL 查詢與常見陷阱
- MariaDB 遷移（Bitnami Galera → 官方 StatefulSet） — mydumper/myloader 平行遷移六個 Phase SOP：匯入加速設定、正式環境切換、Rollback 策略
- MongoDB Helm 部署 — Bitnami Helm Chart 部署 MongoDB：Standalone 與 ReplicaSet 架構比較、externalAccess 陷阱
- PgBouncer 連線池（Kubernetes 部署） — PostgreSQL 連線池：Transaction 模式、SCRAM-SHA-256 認證、auth_query 自動同步
- Redis on Kubernetes 部署與維運 — Bitnami Helm Chart 部署 Redis Master-Replica：多版本安裝紀錄、Internal LoadBalancer、備份還原（dump.rdb / 既有 PVC）、Standalone 快速啟動
- RabbitMQ on Kubernetes 部署 — Cluster Operator + RabbitmqCluster CR 部署：TLS 設定、MQTT 插件、NodePort / LoadBalancer 暴露策略演進、Pika TLS 連線範例
監控
- Prometheus on Kubernetes 部署與設定 — prometheus-community Helm Chart 部署：extraScrapeConfigs 設定、Admin API 啟用、時序資料刪除、所有 Exporter 的 scrape job 設定
- Prometheus Exporter 部署模式 — Exporter 的通用部署模式（Deployment + ClusterIP Service），以 MySQL Exporter 與 Squid Exporter 為例
- Prometheus StatsD Exporter 部署 — 接收應用推送指標（Gunicorn 等）的 StatsD Server：獨立 Helm 部署與 Sidecar 模式、Metric Mapping 設定
- MySQL Exporter 部署 — 直接 YAML 部署 mysqld-exporter：MySQL 帳號建立 SQL、K8s Secret 管理密碼、Deployment + ClusterIP Service 完整設定
- RabbitMQ Exporter 部署 — prometheus-community Helm Chart 部署，透過 ConfigMap 注入 HTTPS Management API 連線資訊
- Redis Exporter 部署 — prometheus-community Helm Chart 部署，連線 Redis Master 採集指標
- Postgres Exporter 部署 — prometheus-community Helm Chart 部署，含 pg_stat_statements 問題修復與多資料庫實例部署方式
- Grafana on Kubernetes 部署 — Bitnami OCI Chart 部署：持久化儲存、NodePort 暴露、匿名登入、grafana.ini 自訂設定
- Node Exporter（VM 系統層監控） — Ubuntu VM 上 systemd 部署：binary 安裝、系統用戶建立、Prometheus scrape_configs 設定、Grafana Dashboard ID 1860
GitLab / CI-CD
- GitLab Omnibus (Docker) HTTPS 連線失敗排除 SOP — 七步驟排除 GitLab Omnibus Docker 部署中 HTTPS 連線失敗：external_url 根因、憑證安裝、Chain 完整性、reconfigure vs restart 陷阱
- 維運 SOP：憑證與帳密更新 — 多系統年度憑證輪替與帳密同步 SOP：K8s/AKS TLS Secret、PostgreSQL VM、GitLab Server、K8s 叢集自簽憑證（kubeadm certs renew）
- GitLab Runner Docker 部署 — Docker Compose 安裝 GitLab Runner、Docker-in-Docker 設定（privileged + socket 掛載）、config.toml 完整參考
- GitLab CI/CD 部署至 Azure App Service — 以 GitLab CI/CD + Azure CLI 部署容器映像或原始碼至 App Service：帳號密碼 vs Service Principal 認證、az webapp up、私人 Registry 設定
- Azure DevOps Pipeline CI/CD 設定指南 — 三種部署情境 YAML：AKS kubectl 冪等部署、App Service 單服務、多服務加 Deployment Slot 與 Commit Message 控制
- Azure DevOps — 禁止直接 Push 到 master Branch SOP — 啟用 Branch Policy 封鎖直接 push、Bypass 權限確認、四步驟 SOP 與驗收指令
- Azure Pipelines Self-Hosted Agent — Ubuntu 安裝與服務設定 — Self-Hosted Agent 在 Ubuntu 上的完整安裝流程：下載、
config.sh向 ADO 註冊、svc.sh設為 systemd 開機服務、服務狀態檢測指令 - CodePush Server on Azure App Service — React Native OTA 更新自架方案：Bicep 基礎設施、az webapp up 部署、Azure AD App Registration 驗證整合、code-push-standalone CLI
- OpenSSL 自簽憑證產生 — 自建 CA 根憑證與伺服器憑證的完整腳本，含 v3 SAN 設定與 sslip.io 技巧
- GitLab LDAP 設定更新 — 修改 gitlab.rb LDAP 區塊並驗證的三步驟 SOP：vi → reconfigure → ldap:check
- AAD / LDAP 查詢工具指南 — ldapsearch 查詢 Active Directory 使用者資訊，含 LDAP Server 清單與 bind 帳號，以及 Azure AD Domain PowerShell 查詢
- Azure Pipeline — Kubeconfig 隔離最佳實踐 — self-hosted runner 使用
Agent.TempDirectory+KUBECONFIG環境變數隔離 kubeconfig，避免 race condition 與憑證殘留 - Azure Blob Storage 連線與分享 — 多種認證方式（DefaultAzureCredential / Connection String / SAS）、非程式工具（AzCopy / Storage Explorer / rclone）、SAS 產生與 Stored Access Policy 完整指南
Web 伺服器
- React + API + DB 服務遠端部署方案 — 單台 VPS + Cloudflare Tunnel 將 docker-compose 全棧服務商業化：三大方案比較（VPS / PaaS / Workers）、DNS Proxy vs Tunnel 決策、VPS 規格選型（Hetzner/Vultr/DO）、Postgres 調教、踩雷清單與 12 步 Action Items
- Caddy 靜態檔案伺服器 — Caddy 取代 Nginx 的靜態檔案伺服器：分層快取策略、目錄瀏覽白名單、內建 Prometheus metrics
- Nginx Reverse Proxy to Self（反向代理回自身） — 同一台機器兩個 server block 分離外部入口與內部應用邏輯，Host header 改寫路由
- Nginx 反向代理與負載平衡設定 — 標準 HTTP L7 反向代理（proxy_pass + 四標準 Header）與 TCP/UDP L4 Stream 負載平衡（K3s API Server HA 範例，least_conn 演算法）
- Nginx 檔案服務 Server — autoindex 原生方案與 fancyindex 美化版（Alpine Dockerfile + docker-compose），含 Alpine 路徑差異注意事項
- Gunicorn 原生 ASGI Worker — Gunicorn 25.1.0 stable ASGI Worker：從 UvicornWorker 一行遷移、WebSocket 支援、uvloop 整合、Nginx HTTP Proxy 設定、Docker 部署範例
郵件服務
- SMTP 郵件伺服器（Kubernetes 部署） — 輕量 SMTP 轉發伺服器：ixdotai/smtp 映像、Smarthost 轉發至 Exchange Online Protection
檔案分享
- Samba + Nginx 檔案分享服務（Kubernetes 部署） — Samba SMB 分享 + Nginx Web 目錄瀏覽：Sidecar 共享儲存、Basic Auth、fancyindex 美化介面
- SFTP on Kubernetes 部署 — atmoz/sftp 與 SFTPGo 兩種方案比較；AKS 最新架構：SFTPGo + 獨立 Caddy Deployment（3 replicas，port 80 內部 / 81 公開）+ 分層快取 Caddyfile；WebAdmin CSRF Token 修復（signing_passphrase + TOKEN_VALIDATION + externalTrafficPolicy Local）、使用者 SSH Key 認證設定
NAS 與自架服務
- Cloudflare Tunnel x Synology NAS 架構指南 — 零 port 開放的 NAS 外部存取：cloudflared Docker 容器、Origin Certificate（15 年效期）、多服務 Public Hostname 映射、SSL Full/Full Strict 模式選擇
- NAS 自建 Nextcloud（LinuxServer.io） — LSIO 映像（內建 nginx + php-fpm + cron）部署 Nextcloud + MariaDB + Redis + Cloudflare Tunnel：External Storage 全量掃描排程、occ 反斜線加倍問題、Chunked Upload 95 MiB 設定
- Nextcloud + Memories 完整部署（FPM + go-vod） — 官方 FPM 映像 + 自訂 Dockerfile（ffmpeg）+ Nginx + go-vod VA-API 轉碼 + Recognize AI 標籤：supervisord 三程序架構、J4125 WASM 模式、ignore markers、完整 nginx.conf
- Quartz + Cloudflare Pages 部署 — Obsidian 知識庫線上化 SOP：Quartz 4 建站、quartz.config.ts（zh-TW/wikilinks/SPA）、Cloudflare Pages Build 設定（NODE_VERSION=22、git fetch --unshallow）、GitHub Actions 跨 Repo 同步
- Watchtower — Docker 容器自動更新 — 自動偵測 image 更新並重啟容器：Label Enable 模式精確控制受管容器、6 段式 Cron 排程、Email 通知、WATCHTOWER_CLEANUP 自動清理舊 image
媒體處理
- FFmpeg NVENC 硬體加速壓製（H.264 相容方案 / HEVC 平衡方案） — RTX 3060 雙方案：H.264 最廣相容性（Jellyfin Direct Play）與 HEVC 10-bit 高效壓縮（MPV TV Client），含 VBR+CQ、multipass、品質微調對照表
Linux 桌面
- Pop!_OS 上執行 Windows 日系遊戲（Bottles / Wine） — Bottles（Flatpak）建立隔離 Wine 環境執行免安裝 .exe 日系遊戲：日文 locale 設定、cjkfonts 依賴、NVIDIA 獨顯指定、Steam 捷徑注意事項
最近更新
衍生產出
查看 衍生產出目錄(derived/) 瀏覽所有問答記錄、投影片與圖表。
| 日期 | 類型 | 文件 | 摘要 |
|---|---|---|---|
| 2026-05-14 | 校驗報告 | lint-2026-05-14 | 79 篇全庫校驗；自動修正 tags.md 統計（kubernetes/ai-tooling/概念型）、superpowers 日期欄位、log.md 檔名 typo、index.md 統計與衍生產出補列；嚴重 1 項持續未修（azure-graph-api 明文密碼） |
| 2026-04-14 | 校驗報告 | lint-2026-04-14 | 61 篇全庫校驗；1 項自動修正（prometheus-exporter tag）；嚴重 1 項（azure-graph-api 明文密碼）；一般 6 項 |
| 2026-04-14 | 問答記錄 | q-explore-position-in-flowchart | /opsx:explore 為 AI slash command，須在 openspec init 後才能執行；流程圖順序修正 |
| 2026-04-14 | 問答記錄 | q-openspec-sync-manual-changes | Spec Drift 場景：以 /opsx:sync（Expanded profile）反映中途手動開發 |
| 2026-04-14 | 問答記錄 | q-superpowers-writing-plans-necessity | writing-plans 為從 /opsx:propose 規格到 subagent-driven-development 任務封包的必要中間轉換層 |
| 2026-04-13 | 問答記錄 | q-superpowers-workflow-sync | /opsx:sync 是 Optional 且 archive 自動涵蓋，整合工作流應移除此步驟 |
| 2026-04-12 | 問答記錄 | q-copilot-subagent-vs-claude-code | GitHub Copilot Sub-Agent 與 Claude Code 的功能差異比較 |
| 2026-04-11 | 校驗報告 | lint-2026-04-11 | 22 篇文章的格式與內容校驗結果 |
統計
- 概念文章數：87
- 衍生產出數：8
- 原始素材編譯數：97