---
title: "團隊控制與排障"
description: "整理 Windsurf Admin Portal、SSO/SCIM、RBAC、命令策略、MCP 准入、共享、日誌和常見故障定位。"
verifiedAt: "2026-05-09"
---

Windsurf 進入團隊後，問題不再是“會不會提問”，而是組織治理：誰能用哪些模型，Cascade 能不能自動跑命令，MCP 能訪問哪些系統，對話能否共享，成員如何入職和離職，故障日誌怎麼收集。

官方 Guide for Admins 把目標讀者定義為 enterprise platform / developer-experience admins、Corporate IT 和 centralized tooling teams。它不是單純的使用者教程，而是部署和運營清單。

> [!TIP]
> **閱讀目標**：讀完本章，你應該能為團隊上線 Windsurf 列出 Day 0 檢查、許可權邊界和常見排障路徑。

## 1. Admin Portal 是團隊控制面

官方 Guide for Admins 說明，Admin Portal 提供集中管理能力，包括 user/team management、credit usage、**SSO**（Single Sign-On 單點登入，員工用公司 Google/Okta/Azure AD 賬號登入 Windsurf）、feature toggles、analytics、service keys 和 role/permission controls。

> [!NOTE]
> **幾個企業身份術語先速通**：**SSO** = 單點登入（用公司賬號登 Windsurf）；**SCIM**（System for Cross-domain Identity Management）= 跨域身份管理協議，讓公司 IdP 自動給 Windsurf 建立 / 停用賬號；**RBAC**（Role-Based Access Control）= 基於角色的許可權控制（按"管理員 / 普通使用者"等角色批次發許可權，而不是逐人配）；**IdP**（Identity Provider）= 身份提供商（Okta / Azure AD / Google Workspace 等存員工賬號的系統）。

團隊上線前先定這 7 件事：

| 控制面 | 官方能力 | 上線判斷 |
| --- | --- | --- |
| Identity | SSO、SCIM、RBAC | 是否用 IdP group 管使用者生命週期 |
| Models | 按 model 或 provider 過濾，設定 default Cascade model | 是否有模型白名單和預設模型 |
| Terminal | 最大 auto-execution level，團隊 allow/deny list | 是否禁止生產儲存庫 Turbo |
| MCP | 開關 MCP access、維護 whitelisted servers | 是否審查每個 server 的許可權 |
| Sharing | 團隊內 conversation sharing | 是否有脫敏規則 |
| Analytics/API | usage dashboards、service keys、analytics API | 是否有負責人看用量和採用情況 |
| RBAC | 預設 Admin/User 角色、自定義角色、許可權分類 | 是否按最小許可權授予 analytics、billing、service key、role management |

```mermaid
flowchart TD
    Admin["Admin Portal"] --> Identity["SSO / SCIM / RBAC"]
    Admin --> Models["Models Configuration"]
    Admin --> Terminal["Terminal Commands"]
    Admin --> MCP["MCP Servers"]
    Admin --> Share["Conversation Sharing"]
    Admin --> Analytics["Analytics / API"]
    Identity --> Onboard["入職 / 離職 / 分組"]
    Terminal --> Guard["命令執行邊界"]
    MCP --> Data["外部系統資料邊界"]
    Analytics --> Cost["用量和費用負責人"]

    style Admin fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style Guard fill:#fee2e2,stroke:#dc2626,stroke-width:2px
```

## 2. Day 0 上線清單

官方 quick-start checklist 包含確認組織設定、設定 SSO、啟用 SCIM 並把 IdP groups 對映到 Windsurf teams、定義 role/permission model、配置 Admin Portal、分發 client/extensions、檢視 analytics 和 API access tokens。

落到研發團隊，可以拆成這張清單：

| Day 0 項 | 必須確認 |
| --- | --- |
| 身份 | SSO 是否啟用，SCIM 是否負責自動建立/停用使用者 |
| 角色 | 誰是 admin，誰能看 analytics，誰能生成 service keys |
| 模型 | 允許哪些 model/provider，預設模型是什麼 |
| 命令 | 最高 auto-execution level，團隊 allow/deny list |
| MCP | 是否啟用 MCP，哪些 server 被 whitelist |
| 專案規則 | root `AGENTS.md`、`.windsurf/rules/`、`.codeiumignore` 是否準備好 |
| 共享 | 對話分享是否僅團隊可見，是否有脫敏規則 |
| 支援 | 日誌、support、status page 和內部聯絡人是誰 |

## 3. 身份和成員生命週期

官方建議儘可能使用 SSO + SCIM，實現自動 provisioning、de-provisioning 和 group management。SSO 支援 Okta、Azure AD、Google，以及 generic SAML；SCIM 可以自動建立/停用使用者、建立 teams，使用者也可以屬於多個 teams。

關鍵邊界：

- 不要用 `All Employees` 這類大組直接放開開發許可權。
- 用 role-based group assignments，把不同專案或職能對映到 Windsurf teams。
- SCIM 應儘量保持 source of truth，避免混合手工/API 改造成 drift。
- 組命名要提前規劃，因為 Windsurf team 是 flat collection，沒有 nested teams 可兜底。
- Windsurf 只支援 SP-initiated SSO；不要按 IdP-initiated SSO 設計入口。
- Microsoft Entra 配置裡 IdP Entity ID 可能需要保留 trailing slash，測試登入前不要關閉設定頁。

RBAC 只在 Enterprise 可用。官方 RBAC 頁面列出預設 Admin Role 和 User Role，也提供 Analytics、Teams、Indexing、SSO、Service Key、Billing、Role Management、Team Settings 等許可權分類。團隊不要把“能看 analytics”和“能改 billing / role / service key”放在同一個預設角色裡。

## 4. 命令、MCP 和共享的安全邊界

官方 Admin Guide 對幾個高風險能力都提供了管理員控制。

| 能力 | 管理員應設定 | 風險 |
| --- | --- | --- |
| Auto Run Terminal Commands | 組織最高 level；推薦生產不開放 Turbo | 自動執行刪除、部署、基礎設施命令 |
| Terminal Command Lists | 團隊 allowlist / denylist；deny 優先 | 個人配置繞過團隊策略 |
| MCP Servers | 是否開啟 MCP、whitelist approved MCP servers | MCP 可能建立 Windsurf 監控外的基礎設施資源 |
| App Deploys | 管理 Cascade 裡的部署許可權 | 誤部署、錯誤環境、許可權擴散 |
| Conversation Sharing | 團隊內分享開關 | 對話含私有路徑、客戶資料、token |

> [!WARNING]
> **MCP 和終端不是普通外掛能力**。它們能觸達外部系統和本機命令。團隊上線前必須有白名單、deny list、owner 和撤權路徑。

<details>
<summary>深讀：為什麼 feature toggles 要按團隊分階段開啟</summary>

官方 Admin Guide 特別提示：帶資料隱私影響的新 major features 預設以 off 狀態釋出，讓管理員控制何時、如何啟用。這個設計說明 Windsurf 的團隊能力會涉及真實程式碼、對話、外部工具和遙測。

更穩的上線方式是先在低風險團隊開啟，只允許只讀 MCP 和低風險命令；確認日誌、撤權、費用和共享策略後，再擴到生產團隊。
</details>

## 5. 常見排障路徑

官方 Common Issues 覆蓋 rate limiting、Python 擴充套件、diagnostic logs、macOS 安全彈出視窗、Windows 更新、Remote SSH、網路白名單、Linux launch、Cascade panel blank、Terminal stuck、WSL Docker container 等問題。

| 現象 | 官方線索 | 先做什麼 |
| --- | --- | --- |
| Pro 訂閱仍顯示 Free | 等幾分鐘、登出網站、重啟 IDE、重新登入、確認最新版本 | 不要先重灌系統 |
| rate limiting | premium models 可能遇到容量限制 | 等待後重試，必要時切模型 |
| Python 語法/型別異常 | 官方提供 Windsurf Pyright 擴充套件 | 搜尋 `Windsurf Pyright` 或 `@id:codeium.windsurfPyright` |
| 需要發 support | Cascade panel 三點選單可下載 diagnostics | 先下載日誌，再復現問題 |
| macOS “damaged” 彈出視窗 | Privacy & Security 允許，確認架構版本，必要時重下 DMG | 不要用非官方包 |
| Windows 更新異常 | user-scope install 以 Administrator 執行會影響 auto-update | 以 user scope 執行 |
| macOS Remote SSH `Undefined error: 0` | Local Network 許可權被 macOS 攔截 | Privacy & Security -> Local Network 允許 Windsurf |
| 網路過濾/VPN/proxy | 需 whitelist `*.codeium.com`、`*.windsurf.com`、`*.codeiumdata.com` | 先讓網路團隊放行域名 |
| Linux 不啟動 | chrome-sandbox 許可權問題 | 按官方命令修許可權，儘量不用 `--no-sandbox` |
| Cascade panel blank | 可能需要 support，清空 chat history 會影響本地歷史 | 先備份/記錄，再處理 |
| Terminal stuck | 預設 terminal profile、zsh theme、Linux systemd OSC context 都可能影響解析 | 簡化 shell 配置或用專用最小配置 |
| WSL Docker 容器不可見 | Remote Explorer 不顯示容器 | 用 command palette `Dev Containers: Attach to Running Container` |

## 6. 網路、代理和證書排障

企業網路裡，Windsurf 問題經常不是 IDE 本身，而是 proxy、SSL inspection、VPN 或 zero-trust 軟體。

官方 proxy 頁面給出的判斷順序：

1. 先問 IT 是否使用 HTTP/HTTPS proxy。
2. 如果系統已有代理或 PAC，優先嚐試 Windsurf Settings 裡的 `Detect proxy`。
3. 如果 IT 給了固定 proxy URL 和憑據，就在 Windsurf Settings 手動配置。
4. SSH remote / dev container 有獨立的 remote proxy 設定，不等同於本地 editor proxy。
5. 改完 proxy 後重啟 Windsurf 或重連 remote session。

官方 SSL inspection 頁面建議從 Developer Tools Console 收集真實錯誤。常見模式包括：

- `certificate signed by unknown authority`
- `unable to verify the first certificate`
- `self signed certificate in certificate chain`
- `unable to get local issuer certificate`
- `handshake_failure`
- `ERR_SSL_PROTOCOL_ERROR`

給 IT 的資訊要包含失敗時間、OS、是否安裝 Zscaler 等客戶端、expanded console error、熱點網路是否正常、是否只在公司網路失敗。優先修企業 CA trust chain；無法對齊時，再申請 scoped SSL inspection bypass。

## 7. WSL 和 Linux 專項問題

官方 WSL Known Issues 頁面把慢、斷連和安裝失敗分成兩類。

| 問題 | 根因 | 處理 |
| --- | --- | --- |
| WSL 慢、斷連、記憶體增長 | 9P 檔案系統被擴充套件和語言服務大量 file watching 飽和 | 清理 `~/.windsurf-server`、減少 WSL 內擴充套件、調整 `.wslconfig` |
| VPN/zero-trust 下無法安裝 WSL server | WSL 2 NAT 網路流量被 VPN / Tailscale / Zscaler / WARP 等攔截 | 開啟 mirrored networking、dnsTunneling、autoProxy，或臨時斷開 VPN |
| Linux language server 報 “No space left on device” | inotify watches / instances 耗盡，不是真磁碟滿 | 提高 `fs.inotify.max_user_watches` 和 `fs.inotify.max_user_instances` |

inotify 常用診斷：

```bash
cat /proc/sys/fs/inotify/max_user_watches
cat /proc/sys/fs/inotify/max_user_instances
find /proc/*/fd -lname anon_inode:inotify 2>/dev/null | wc -l
```

官方建議的大儲存庫修復值：

```bash
sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl fs.inotify.max_user_instances=1024
```

永久修改再寫入 `/etc/sysctl.conf` 並執行 `sudo sysctl -p`。這類操作會影響系統級資源限制，團隊機器應由 IT/infra 統一處理。

## 8. 日誌採集順序

官方 Gathering Windsurf Logs 頁面提供兩條路徑：

1. Command Palette：`Download Windsurf Logs` → `Download Windsurf Logs File`。
2. Cascade panel 右上角三點選單：`Download Diagnostics`。

提交 support 或內部工單前，至少附上：

- Windsurf 版本、OS、安裝方式。
- 復現步驟和時間點。
- 是否公司網路、VPN、proxy、SSL inspection、WSL、SSH remote、dev container。
- 相關日誌檔案。
- 如果是網路/TLS 問題，附 Developer Tools Console 的 expanded error。
- 如果是終端 stuck，附最小 shell 配置和 default terminal profile。

## 9. 組織級上線標準

商業團隊至少要做到：

1. 有專案級 `AGENTS.md`，寫明命令、測試、部署和敏感資訊邊界。
2. 有 `.codeiumignore`，排除金鑰、生成物、大型快取和私密資料。
3. 有團隊命令 allow/deny 策略，生產儲存庫停用 Turbo。
4. 有 MCP server 准入名單、owner、認證方式和撤權路徑。
5. 有 conversation sharing 脫敏規範。
6. 有模型和用量負責人。
7. 有 diagnostic logs、support 和 status page 的排障路徑。
8. 有新成員 onboarding 和離職 de-provisioning 流程。
9. 有 proxy、SSL inspection、WSL、Linux inotify 的企業環境排障 SOP。

這些不是形式主義。Windsurf 會讀程式碼、執行命令、呼叫工具、儲存上下文；它已經屬於工程治理系統。

## 本章自檢

完成本章後，用這 4 個問題檢查：

1. 團隊是否用 SSO + SCIM 管理使用者生命週期？
2. 管理員是否限制了模型、命令和 MCP？
3. 專案是否有 `AGENTS.md` 和 `.codeiumignore`？
4. 常見網路、終端、日誌、訂閱、WSL 問題是否有排障入口？

透過標準：你能把 Windsurf 從個人工具上線成團隊可治理的開發系統。

## 官方來源

- [Guide for Admins](https://docs.windsurf.com/windsurf/guide-for-admins) —— 官方企業管理員指南，覆蓋 SSO、SCIM、RBAC、Admin Portal、feature toggles、analytics、API 和 end-user onboarding。
- [Role Based Access & Management](https://docs.windsurf.com/windsurf/accounts/rbac-role-management) —— 官方 RBAC 頁面，覆蓋角色、許可權分類、service key、billing、role management 和 user groups。
- [Setting up SSO & SCIM](https://docs.windsurf.com/windsurf/accounts/sso-scim) —— 官方 SSO / SCIM 頁面，覆蓋 Google、Microsoft Entra、Okta、generic SAML 和 SP-initiated SSO 邊界。
- [Terminal](https://docs.windsurf.com/windsurf/terminal) —— 官方終端文件，說明團隊級 command lists、auto-execution 上限和 deny 優先。
- [Model Context Protocol (MCP)](https://docs.windsurf.com/windsurf/cascade/mcp) —— 官方 MCP 文件，說明 registry、whitelist 和 server matching。
- [Common Windsurf Issues](https://docs.windsurf.com/troubleshooting/windsurf-common-issues) —— 官方排障頁，覆蓋訂閱、rate limit、diagnostics、系統許可權、網路白名單、Linux、Terminal 和 WSL。
- [Gathering Windsurf Logs](https://docs.windsurf.com/troubleshooting/windsurf-gathering-logs) —— 官方日誌採集頁面。
- [Proxy Configuration](https://docs.windsurf.com/troubleshooting/windsurf-proxy-configuration) —— 官方代理配置頁面。
- [TLS / SSL Inspection Issues](https://docs.windsurf.com/troubleshooting/windsurf-ssl-inspection) —— 官方 SSL inspection 排障頁面。
- [WSL Known Issues](https://docs.windsurf.com/troubleshooting/windsurf-wsl-performance) —— 官方 WSL 9P、VPN、zero-trust 排障頁面。
- [Language Server inotify limits](https://docs.windsurf.com/troubleshooting/windsurf-inotify-limits) —— 官方 Linux inotify 限制排障頁面。

## 接下來去哪

<Cards>
  <Card title="返回官方教程索引" description="回到 Windsurf 官方中文版入口，按安裝、Cascade、上下文、MCP、團隊治理完整覆盤。" href="/zh-Hant/docs/windsurf/official" />
  <Card title="對比 Cursor / Claude Code / Codex" description="繼續從真實專案角度比較 Windsurf 和主流 AI 程式設計工具。" href="/zh-Hant/docs/windsurf/understanding/08-windsurf-vs-cursor-claude-code-codex" />
</Cards>
