部署 Office 加载项

加载项有两种部署形态：本地 sideload 只用于开发验证；生产走 M365 管理中心集中分发。背景与能力总览见 Office / Microsoft 365 加载项。

前置准备

• 拿到部署包：gatellm-for-msft-365-localhost 包由 GateLLM 向签约客户提供，不公开下载；尚未获取时先经官网产品页接洽。包是一个自包含目录，含 start.sh / sideload.sh（本地启动与安装）、scripts/build-manifest.mjs（manifest 生成）、webroot/（预打包的 scrubbed SPA）、templates/（manifest 模板）、commands/（全部操作手册：consent、Entra app、access_policies、排错等）。下文所有命令都在包目录内执行。
• Node.js 18+。
• mkcert（brew install mkcert）：签受信任的本地 TLS 证书；为什么不能用 openssl 自签见踩坑 1。
• 网关地址（公网域名 + 受信 HTTPS 证书）+ API key：网关怎么跑起来见快速部署各页（如 Docker 单机）。注意：localhost 起的网关不能用于加载项——网关必须部署在有公网域名 + 受信 CA 证书的地址上，见下方警告与踩坑 2。
• （按需）你自己租户里注册的 Entra app：用 entra_scope / gateway_auth_source=entra，或不用默认多租户 app 时需要，见下文「注册自己的 Entra app」。

localhost 网关不能用于加载项测试

本机起一个 HTTPS 网关（哪怕证书本地受信），Office WebView 也连不上——实测就是连不通。本地网关只能验证网关自身；加载项的端到端验证必须先把网关部署到有公网域名 + 受信 CA 证书的地址（staging 环境即可），再把 GATEWAY_URL 指向它。

本地 sideload（开发验证）

1. 配置网关凭据：

   cp .env.example .env   # 填入 GATEWAY_URL（公网域名的 HTTPS 地址，不能是 localhost）与 GATEWAY_TOKEN

2. 启动并安装：

   ./start.sh            # 读 .env → 签证书 → 生成 manifest → 起 HTTPS 服务
   ./sideload.sh         # 装 office（TaskPane）manifest
   ./sideload.sh --outlook   # 或装 outlook（Mail）manifest
   ./sideload.sh --clear     # 卸载

3. 验收：退出并重开 Excel / Word / PowerPoint → Insert → My Add-ins 里出现 Gatellm（验证装载成功；与模型的端到端对话还要求网关在公网域名上，见上方警告）。

sideload 用自签证书，Office 对 localhost 较宽松；浏览器打开 https://localhost:8443 会有证书警告，正常。

生产：M365 管理中心集中分发

生产部署分两半：SPA 上 CDN 和 manifest 上传 M365 管理中心。

1. 托管 SPA：把包内 webroot/ 目录静态托管到你的 CDN（S3 + CloudFront、Azure Static Web Apps、nginx 等）。
2. 生成生产 manifest（把 taskpane_url 指向 CDN origin）：

   node scripts/build-manifest.mjs office manifests/manifest-office.xml \
     taskpane_url=https://gatellm-addin.your-cdn.example \
     gateway_url=https://llm-gateway.your-org.example \
     entra_sso=1 graph_client_id=<guid> gateway_auth_source=entra

   两个宿主是两个独立的加载项（Office 版 TaskPaneApp / Outlook 版 MailApp，权限模型不同）：各自生成 manifest、各自上传、各自管版本。同时部署 Outlook 就用 outlook 再生成一份。
3. 校验 manifest：

   npx --yes office-addin-manifest validate manifests/manifest-office.xml

4. 上传：M365 Admin Center → Settings → Integrated apps → Upload custom apps。验收：用户在 Office 里打开加载项，能直接进入对话。

生产硬性要求：

• manifest 的 <SourceLocation> 必须公网可达 HTTPS + 受信 CA 真证书（不是自签）。
• 全程 HTTPS，SPA 里的 .js / .mjs 必须以 text/javascript MIME 提供。

Outlook / Entra 管理员同意

有两类同意，互相独立：

同意	何时需要	谁做
Entra SSO 同意	entra_sso=1 且用默认多租户 app	Global Admin，每租户一次
Microsoft Graph 同意（邮箱 / 日历）	部署 Outlook manifest 就必需（与 entra_sso 无关）	Global Admin，每租户一次

• 默认多租户 app：包内 commands/consent.md 给出对应的一次性同意 URL，Global Admin 在已登录的浏览器里打开、点 Accept 即可。不做这一步，每个用户首次打开都会撞 "Need admin approval"；完成后可用 az ad sp show 验证服务主体已进租户（命令见同册）。
• 用自己的 Entra app（设了 graph_client_id）：上面的同意 URL 不适用——同意直接在你自己的 app 上管理，见下一节。
• 政策禁止给三方 app 授权：注册自己的单租户 Entra app，授同一组 Graph 委托权限（Mail.ReadWrite / Calendars.Read / People.Read / User.Read / offline_access）并做管理员同意，再把它的 client ID 作为 graph_client_id 传入 Outlook manifest。数据流不变，只是批准对象换成你的 app。

不是所有部署都需要 Entra 同意

不设 entra_sso=1 的静态网关 / Vertex 组织级配置用不到 Entra SSO 同意；但只要部署 Outlook，Graph 同意依然必需。

注册自己的 Entra app

设置 graph_client_id（Outlook）、entra_scope、gateway_auth_source=entra 中任一项时，都需要在你自己的租户注册一个 app。清单如下，完整步骤与排错（AADSTS50011 / AADSTS65001 等）在包内 commands/entra-app.md：

1. Entra admin center → App registrations → New registration（单租户）。最简形态：一个 app 同时充当登录客户端与 token 资源。
2. 重定向 URI（登记在 SPA 平台下，不是 Web / Mobile），两条都按加载项的加载 origin 推导（自托管即你的 taskpane origin）：
   • SPA：https://<你的-origin>/msal-redirect.html
   • NAA broker：brk-multihub://<你的-host>（只写 origin 的主机部分——不带协议头、不带路径，有端口则带端口；由 Office 宿主运行时按加载 origin 拼装）。举例：加载 origin 为 https://gatellm-addin.your-cdn.example 时登记 brk-multihub://gatellm-addin.your-cdn.example；origin 带端口（如 https://addin.example:8443）时登记 brk-multihub://addin.example:8443。 缺任一条，登录报 AADSTS50011。
3. Expose an API（entra_scope / gateway_auth_source=entra 必需）：Application ID URI 设为 api://<app-guid> → 添加 scope（如 access_as_user，允许管理员同意）→ 在 API permissions 里把该 scope 作为委托权限授予 app 自身。部署 Outlook 则另加 Microsoft Graph 委托权限（清单见上一节）。
4. 授予管理员同意（Grant admin consent for <tenant>）。漏了这步，每个用户都会看到同意对话框，或在禁用用户同意时被直接拒绝。
5. 在 app Manifest 里设 "accessTokenAcceptedVersion": 2（仅当做了第 3 步 Expose an API）。不设则 Entra 发 v1.0 token（iss 不带 /v2.0、无 preferred_username），多数 JWT 中间件默认拒收。

网关侧对这张 token 做 iss / aud / scp 校验（JWKS 验签），网关怎么配见 配置 SSO 企业登录。

六条踩坑清单

以下每条都在包 README 排错表里实测过，按部署顺序排：

1. 证书必须用 mkcert。openssl 自签证书会被 Office WebView 拒收，报 Add-in Error — can't load the add-in。brew install mkcert 后用 mkcert -install 把本地 CA 装入系统信任域。

2. GATEWAY_URL 必须是「公网域名 + 受信 HTTPS 证书」，localhost 不行。① http:// 网关会被 Office WebView 的混合内容策略本地拦截，表现为 add-in 里 Could not reach gateway，且网关侧监控不到任何请求（请求压根没发出去）；② localhost 起的网关即使走 HTTPS、证书本地受信，Office WebView 实测也连不上——本地网关没法给加载项做端到端测试，必须部署到有公网域名 + 受信 CA 证书的地址。

3. 浏览器直开 https://localhost:8443 跳 gatellm.io/downloads 是正常的。这是 SPA 的 host 检测——发现「不在 Office 宿主里」就引导下载。加载项必须在 Office 里打开，不是在浏览器里。

4. CDN 必须满足三点：.js / .mjs 供成 text/javascript MIME；目录索引设为 index.html；配置 SPA fallback 把未知路径回 index.html（给 /auth/callback 用）。否则 chunk 404 / MIME 错误。

5. 所有运行时 fetch 目标都要放行 CORS。bootstrap_url、mcp_servers[].url、skills[].url、otlp_endpoint 的响应头都要放行 taskpane origin：

   Access-Control-Allow-Origin: https://gatellm-addin.your-cdn.example

6. 同 <Id> 同 <Version> 重传会被静默忽略。M365 Admin Center 按 ID + Version 缓存，改 <Version> 第四段（如 1.0.0.9 → 1.0.0.10）再传。

下一步

• Office / Microsoft 365 加载项 看能力、治理与数据面。
• 网关侧按真实用户鉴权 / 计费，配合 配置 SSO 企业登录。