使用 Docker 與專用 GitHub App 憑證私有化部署 Sweep：企業本地程式碼自動化指南

在金融科技、生醫醫療、智慧硬體與關鍵企業基礎設施等高度合規管制的研發環境中，導入自動化程式碼修復與開發代理（AI Coding Agent）常面臨嚴格的資安紅線：企業資安政策嚴厲禁止將專利與核心商務程式碼傳輸至外部多租戶公有雲。開源 AI 開發者代理 Sweep（儲存庫 sweepai/sweep）的容器化自託管架構，正是化解此架構痛點的實踐路徑。透過在私有 VPC 或內網實體伺服器中以 Docker 部署 Sweep 映像檔，並串接專屬 GitHub App 授權機制與內網 Webhook 監聽器，DevOps 工程師能在「原始程式碼資產零外流」的最高防護前提下，建立從 Issue 提出到 Pull Request（PR）產生的端到端自動化閉環。

本指南提供深入淺出的架構剖析與可落地的工程實作步驟，涵蓋伺服器硬體規格、專屬 GitHub App 權限設定、Docker Compose 部署編排、反向代理安全防護以及零停機維運策略。

架構剖析：Sweep 私有化部署如何運作

在內部網路環境維運 Sweep，必須釐清其容器內部服務如何與 GitHub 儲存庫以及大語言模型（LLM）API 協同運作：

[GitHub / GitHub Enterprise]
       |
       |  1. Webhook 事件推播（issues, PR 評論）
       v
[反向代理 / 邊界閘道器 (TLS 終止與 GitHub IP 白名單)]
       |
       |  2. HTTP 8080 埠轉發（HMAC-SHA256 簽章驗證）
       v
[Sweep 容器 (`sweepai/sweep`)]
  ├── Webhook 快速回應處理器 (FastAPI / Uvicorn)
  ├── 非同步任務佇列調度中樞 (內建 Redis + 背景工作行程)
  ├── 程式碼感知引擎 (Ripgrep 符號搜尋 + GitHub Linguist + AST 語法剖析)
  └── 工作區持久化快取掛載 (`/mnt/caches`)
       |
       |  3. 僅對外發送去識別化的上下文 Prompt
       v
[企業專屬 LLM API (OpenAI / Anthropic / 私有閘道)]
       |
       |  4. 回傳程式碼補丁計畫與 Diff
       v
[Sweep Git 執行引擎]
       |
       |  5. 依據 GitHub App 私鑰簽發 Token，推送分支並建立 PR
       v
[目標程式碼儲存庫 (自動生成新分支與 Pull Request)]

內網 Webhook 接收與鑑權：當開發者在儲存庫中建立以 Sweep: 為前綴的 Issue 時，GitHub 會將事件 JSON 酬載推送至 Sweep 的 8080 埠。Sweep 會利用環境變數中設定的 WEBHOOK_SECRET，透過 HMAC-SHA256 演算法核驗 HTTP 標頭簽章，杜絕偽造攻擊。
非同步佇列解耦：GitHub 要求 Webhook 端點必須在 10 秒內回應 HTTP 請求。Sweep 接獲合法請求後，會立即將任務推入內部 Redis 佇列並回傳 HTTP 200，由背景工作行程負責耗時的程式碼檢索與修復邏輯。
本地程式庫索引與分析：容器內建了高速檢索工具 ripgrep、語言識別套件 github-linguist 以及 tree-sitter 語法樹剖析工具。程式碼會在臨時工作區被分析，相關的快取與向量索引會儲存在實體機的 /mnt/caches，避免每次重新索引。
LLM 編排與隱私界線：Sweep 僅將修復所需的關聯程式碼片段與提示詞（Prompt）發送至企業設定的 OPENAI_API_KEY 或 ANTHROPIC_API_KEY。在搭配企業專屬「零資料保留（Zero Data Retention）」條款或專用 API 閘道時，外部大模型服務僅接收有限片段，核心程式庫完整原始碼絕不外流。
權限封裝與 Git 自動化操作：Sweep 根據設定的專屬 GitHub App ID 與 RSA 私鑰（GITHUB_APP_PEM），在執行階段動態申請短效期的安裝存取權杖（Installation Access Token），拉取最新程式碼、建立 sweep/... 專屬分支、套用修復補丁、提交變更並在 GitHub 上發起 PR。

系統硬體規格與事前準備

Sweep 在執行多檔案語法樹建構、本地檢索與 Git 操作時，需要足夠的計算與記憶體資源，建議依據以下指標配置主機：

建議硬體規格

作業系統：Ubuntu 22.04 LTS、Ubuntu 24.04 LTS 或企業級 Linux 發行版（RHEL 9 / Rocky Linux）。
處理器：最少 4 核心 vCPU（多檔案併發搜尋建議配置 8 核心）。
記憶體：最少 32 GB RAM（若低於 16 GB，大型專案在進行 AST 語法樹載入時極易發生 OOM 崩潰）。
磁碟空間：最少 200 GB SSD 或 NVMe 高速儲存（Git 分支與快取快照極度依賴磁碟 I/O 吞吐量）。
雲端規格對照：AWS t3.xlarge、GCP e2-standard-8 或內部等效虛擬機器。

軟體與網路連線需求

安裝 Docker Engine（v24.0+）與 Docker Compose（v2.20+）。
對外連線：允許透過 TCP 443 埠連線至 LLM API 端點（如 api.openai.com 或 api.anthropic.com）。
對內/對外監聽：確保 GitHub 能連通 Sweep 伺服器的 Webhook 埠。若為 GitHub.com 公有雲，可透過具備 TLS 的 Nginx 反向代理接收；若為企業內建的 GitHub Enterprise Server（GHES），則可直接在企業內部網路完全封閉通訊。

步驟一：建立並設定企業專屬 GitHub App

使用專屬 GitHub App 取代個人存取權杖（PAT），是落實最小權限原則與企業資安稽核的核心要求。

1. 建立 GitHub App

使用組織管理者權限登入 GitHub，進入組織設定頁面，依序點選 Developer settings > GitHub Apps > New GitHub App。
填寫應用程式基本資訊：
- GitHub App name：設定具識別性的名稱（例如 Corp-Internal-Sweep）。
- Homepage URL：填寫內部系統或維運入口網址。
- Callback URL：可保留空白。

2. 設定 Webhook

Webhook URL：輸入反向代理後的安全網址（例如 https://sweep.internal.yourcorp.com/，測試時可使用 http://<主機IP>:8080）。
Webhook secret：使用終端機指令 openssl rand -hex 32 生成高強度隨機金鑰並妥善保存。

3. 配置儲存庫權限（Repository permissions）

依據最小權限原則設定以下項目：

權限項目	存取層級	運作必要性說明
Repository contents	Read and write（讀寫）	允許複製原始碼、開立獨立修復分支並提交程式碼變更。
Issues	Read and write（讀寫）	監聽觸發指令，並在 Issue 中回覆工作進度與修復計畫。
Pull requests	Read and write（讀寫）	自動建立 PR、接收 Review 評論並持續迭代修訂。
Checks	Read and write（讀寫）	讀取 CI 自動化測試結果，以便在測試失敗時自主修正程式碼。
Metadata	Read-only（唯讀）	GitHub 強制預設的基本元資料讀取權限。

4. 訂閱 Webhook 事件（Subscribe to events）

勾選以下事件通知：

Issues（Issue 建立、修改、標籤、指派）
Issue comment（Issue 留言發表）
Pull request（PR 建立、分支更新、審查請求）
Pull request review comment（程式碼行級審查留言）
Check run（CI 測試執行完成）

5. 生成私鑰並完成安裝

將 Where can this GitHub App be installed? 設為 Only on this account（僅限本組織安裝）。
點選 Create GitHub App 完成建立。
在概覽頁記錄數值格式的 App ID（例如 123456）。
向下滾動至 Private keys 區塊，點選 Generate a private key，系統將自動下載 .pem 私鑰檔案。
在左側選單點選 Install App，選擇目標組織，並選定允許 Sweep 介入的特定程式碼儲存庫。

步驟二：配置環境變數檔（.env）

在伺服器上建立專案部署目錄，複製 Sweep 官方原始碼並建立設定檔：

mkdir -p /opt/sweep && cd /opt/sweep
git clone https://github.com/sweepai/sweep.git
cd sweep

建立 .env 檔案並填入相應參數：

# GitHub App 認證參數
GITHUB_APP_ID=123456
GITHUB_BOT_USER=corp-internal-sweep[bot]
WEBHOOK_SECRET=your_generated_webhook_secret_here

# GitHub App 生成的 RSA 私鑰（可為單行跳脫字元格式或多行字串）
GITHUB_APP_PEM="-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n"

# Sweep 授權金鑰
# 評估階段可使用官方 14 天試用金鑰；正式上線需取得企業正式授權
LICENSE_KEY=ABCDE-FGHIJ-KLMNO-PQRST-UVWXY

# 模型推論 API 金鑰（建議綁定具備零資料保留協議之企業金鑰）
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 容器內部執行設定
PORT=8080
WORKERS=3

PEM 格式注意事項：若將私鑰寫為單行環境變數，須將內部的實體換行轉換為 \n。若使用自動化佈署腳本，亦可採用 GITHUB_APP_PEM="$(cat /opt/sweep/github-app.pem)" 動態載入。

步驟三：透過 Docker Compose 啟動容器服務

Sweep 儲存庫內建了多階段 Dockerfile 與 docker-compose.yml 服務定義。

其主要服務編排結構如下：

services:
  hosted:
    build:
      context: .
      dockerfile: Dockerfile
      target: base
    image: sweepai/sweep:local
    container_name: webhook
    env_file:
      - .env
    volumes:
      - .:/app
      - /mnt/caches:/mnt/caches
    ports:
      - "${PORT:-8080}:8080"
    restart: unless-stopped
    command: >
      sh -c ". bin/startup.sh"

啟動服務

建立實體主機快取資料夾並設定存取權限，隨後啟動容器：

sudo mkdir -p /mnt/caches
sudo chown -R 1000:1000 /mnt/caches

# 建置並於背景啟動
docker compose up --build -d hosted

檢視容器運作狀態與即時日誌：

# 檢查容器狀態
docker ps -f name=webhook

# 追蹤即時輸出日誌
docker compose logs -f hosted

當日誌顯示內嵌的 redis-server 正常就緒，且 Uvicorn 工作行程在 0.0.0.0:8080 啟動監聽，即代表 Sweep 後端部署完成。

步驟四：配置安全反向代理與網際網路隔離

在生產環境中，不可將純 HTTP 的 8080 埠直接開放。應在邊界配置 Nginx 進行 TLS 憑證終止，並設定 GitHub 官方來源 IP 白名單防禦非授權掃描。

Nginx 安全反向代理設定範例

upstream sweep_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name sweep.internal.yourcorp.com;

    ssl_certificate /etc/ssl/certs/sweep.internal.yourcorp.com.crt;
    ssl_certificate_key /etc/ssl/private/sweep.internal.yourcorp.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 僅允許 GitHub 官方 Webhook 來源 IP 區段
    # 最新 CIDR 清單可由官方端點 https://api.github.com/meta 中的 "hooks" 欄位取得
    allow 192.30.252.0/22;
    allow 185.199.108.0/22;
    allow 140.82.112.0/20;
    allow 143.55.64.0/20;
    # 允許企業內部測試網段
    allow 10.0.0.0/8;
    deny all;

    client_max_body_size 50M;

    location / {
        proxy_pass http://sweep_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_connect_timeout 10s;
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

備註：若企業採用內部封閉式 GitHub Enterprise Server（GHES），只需在內部 DNS 設定主機對應即可，完全不需開啟任何對外公網連線。

步驟五：端到端工作流程驗證

完成伺服器部署與網路設定後，在授權儲存庫中進行完整驗證：

建立觸發 Issue：在已安裝該 GitHub App 的儲存庫中，建立一個標題帶有 Sweep: 的 Issue，例如：

Title: Sweep: 為 utils/auth.py 新增權杖過期校驗並補齊單元測試
Body: 請針對過期 JWT、簽章毀損與空標頭情境，在 tests/test_auth.py 中撰寫 pytest 測試案例。

檢視 Webhook 接收狀態：在伺服器端觀察容器日誌：
```
docker compose logs -f hosted
```
Sweep 會驗證 Webhook 簽章，向 GitHub 換取安裝存取權杖，並在本地快取區拉取程式碼。
查閱修復計畫回覆：Sweep 會在該 Issue 自動留言，詳述將修改的檔案、架構思路與執行步驟。
確認自動建立的 Pull Request：約 2 至 5 分鐘後，Sweep 會在儲存庫中推送名為 sweep/token-validation-tests 的新分支，並建立包含變更摘要與測試建議的 Pull Request。
測試行級 Review 互動回饋：在 PR 的 Diff 檢視中針對特定程式碼留下 Review 意見（例如：「Sweep: 此處請改用標準函式庫處理時間戳記」），Sweep 會自動接收此 Webhook 並追加 Commit 提交修訂。

維運管理：零停機重載與磁碟清理

Sweep 常在背景執行長時間的程式碼索引與推理，直接執行 docker compose down 可能導致進行中的 Git 交易或分析中斷。

平滑平穩重載（Zero-Downtime Redeployment）

Sweep 專案內建專屬平滑重載腳本：

# 更新專案程式碼或配置
git pull origin main

# 執行平滑重載
bash bin/redeploy.sh

該腳本會在確保現存長任務正常結束後，優雅地重新啟動容器服務。

磁碟維護與快取清理

長期運作下，/mnt/caches 會累積龐大的歷史程式庫索引與暫存檔。建議在 Linux 系統設定每月例行清理的排程工作：

# 清理超過 30 天未存取的工作區快取
find /mnt/caches -mindepth 1 -maxdepth 2 -type d -mtime +30 -exec rm -rf {} +

# 清除未使用的 Docker 映像檔暫存
docker image prune -f

方案比較：自託管部署 vs 官方多租戶雲端版

評估維度	自託管 Sweep（Docker + 專屬 App）	官方 SaaS 多租戶雲端版
程式碼資安與合規性	原始碼、Git 歷史紀錄與語法樹絕不離開企業邊界；完全符合嚴格資安審計標準。	程式碼索引與部分元資料需傳輸至雲端多租戶伺服器處理。
網路隔離支援度	支援完全離線運作（配合 GHES），外部零公網暴露。	必須開放外部伺服器連線至內部儲存庫。
DevOps 維運成本	需自行負責主機效能調優、快取清理、憑證輪替與容器升級。	零維運成本，由官方團隊統一負責架構擴充與軟體更新。
推論成本與費用掌握	依據企業自備之 LLM API 實際用量計費；可套用企業大量合約折讓。	採固定月費或年費訂閱制，受限於每月固定配額與併發數。
審計與除錯可視性	擁有完整的容器系統日誌、Redis 佇列狀態與網路流量存取紀錄。	僅能由平台網頁介面查看摘要紀錄。

DevOps 落地實務建議

嚴選高階推理模型：Sweep 的多檔案修復高度依賴 LLM 的複雜邏輯推理與嚴格 Diff 格式控制。強烈建議搭配 Claude 3.5 Sonnet 或 OpenAI GPT-4o；若嘗試替換為參數量過小的開源模型（例如 7B/8B 模型），經常出現格式破壞、語法錯誤或無限迴圈。
長期技術主權準備：Sweep 早期開源了這套 GitHub Webhook 自動化後端，後續其商業團隊逐步轉向開發 IDE 擴充插件。企業採納此自託管架構時，應將其視為內部 PaaS 平臺進行自主維運與客製化擴充。
金鑰生命週期輪替：應建立每 90 天定期更換 GitHub App RSA 私鑰（.pem）與 WEBHOOK_SECRET 的標準作業流程，確保符合 ISO 27001 與 SOC 2 資安規範。

使用 Docker 與專用 GitHub App 憑證私有化部署 Sweep：企業本地程式碼自動化指南

讓你的 AI 用上 365 Wiki

365Wiki Skill

架構剖析：Sweep 私有化部署如何運作

系統硬體規格與事前準備

建議硬體規格

軟體與網路連線需求

步驟一：建立並設定企業專屬 GitHub App

1. 建立 GitHub App

2. 設定 Webhook

3. 配置儲存庫權限（Repository permissions）

4. 訂閱 Webhook 事件（Subscribe to events）

5. 生成私鑰並完成安裝

步驟二：配置環境變數檔（.env）

步驟三：透過 Docker Compose 啟動容器服務

啟動服務

步驟四：配置安全反向代理與網際網路隔離

Nginx 安全反向代理設定範例

步驟五：端到端工作流程驗證

維運管理：零停機重載與磁碟清理

平滑平穩重載（Zero-Downtime Redeployment）

磁碟維護與快取清理

方案比較：自託管部署 vs 官方多租戶雲端版

DevOps 落地實務建議

參考資料

使用 Docker 與專用 GitHub App 憑證私有化部署 Sweep：企業本地程式碼自動化指南

架構剖析：Sweep 私有化部署如何運作

系統硬體規格與事前準備

建議硬體規格

軟體與網路連線需求

步驟一：建立並設定企業專屬 GitHub App

1. 建立 GitHub App

2. 設定 Webhook

3. 配置儲存庫權限（Repository permissions）

4. 訂閱 Webhook 事件（Subscribe to events）

5. 生成私鑰並完成安裝

步驟二：配置環境變數檔（.env）

步驟三：透過 Docker Compose 啟動容器服務

啟動服務

步驟四：配置安全反向代理與網際網路隔離

Nginx 安全反向代理設定範例

步驟五：端到端工作流程驗證

維運管理：零停機重載與磁碟清理

平滑平穩重載（Zero-Downtime Redeployment）

磁碟維護與快取清理

方案比較：自託管部署 vs 官方多租戶雲端版

DevOps 落地實務建議

參考資料

涉及產品