团队控制与排障

Windsurf 进入团队后，问题不再是“会不会提问”，而是组织治理：谁能用哪些模型，Cascade 能不能自动跑命令，MCP 能访问哪些系统，对话能否共享，成员如何入职和离职，故障日志怎么收集。

官方 Guide for Admins 把目标读者定义为 enterprise platform / developer-experience admins、Corporate IT 和 centralized tooling teams。它不是单纯的用户教程，而是部署和运营清单。

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。

团队上线前先定这 7 件事：

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。

落到研发团队，可以拆成这张清单：

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 对几个高风险能力都提供了管理员控制。

5. 常见排障路径

官方 Common Issues 覆盖 rate limiting、Python 扩展、diagnostic logs、macOS 安全弹窗、Windows 更新、Remote SSH、网络白名单、Linux launch、Cascade panel blank、Terminal stuck、WSL Docker 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 页面把慢、断连和安装失败分成两类。

inotify 常用诊断：

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

官方建议的大仓库修复值：

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 —— 官方企业管理员指南，覆盖 SSO、SCIM、RBAC、Admin Portal、feature toggles、analytics、API 和 end-user onboarding。
• Role Based Access & Management —— 官方 RBAC 页面，覆盖角色、权限分类、service key、billing、role management 和 user groups。
• Setting up SSO & SCIM —— 官方 SSO / SCIM 页面，覆盖 Google、Microsoft Entra、Okta、generic SAML 和 SP-initiated SSO 边界。
• Terminal —— 官方终端文档，说明团队级 command lists、auto-execution 上限和 deny 优先。
• Model Context Protocol (MCP) —— 官方 MCP 文档，说明 registry、whitelist 和 server matching。
• Common Windsurf Issues —— 官方排障页，覆盖订阅、rate limit、diagnostics、系统权限、网络白名单、Linux、Terminal 和 WSL。
• Gathering Windsurf Logs —— 官方日志采集页面。
• Proxy Configuration —— 官方代理配置页面。
• TLS / SSL Inspection Issues —— 官方 SSL inspection 排障页面。
• WSL Known Issues —— 官方 WSL 9P、VPN、zero-trust 排障页面。
• Language Server inotify limits —— 官方 Linux inotify 限制排障页面。

接下来去哪