私有化部署 Cloudflare OS本地跑起来之前的五个坑【免费下载链接】cloudflare-osAgent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-osCloudflare OS 开源之后不少团队的第一反应是把公司上下文搬进一个由 Agent 驱动的操作系统听起来很诱人但数据要留在自己手里那就私有化部署吧。仓库 README 的开头也确实是这么许诺的——pnpm run-local一条命令整个栈在 wrangler 和 workerd 上本地跑起来然后访问 http://localhost:8787 就能体验。但能跑和跑好之间隔着一条很宽的沟。这个项目本质上是 Cloudflare Workers 平台能力的集大成者Durable Objects、Dynamic Workers、Facets、Worker Loaders、KV、R2、SQLite DO、Browser Rendering……其中好几个运行时特性是 Cloudflare 为了支撑 Cloudflare OS 才专门加入的。把这样一套东西搬离云端最先撞上的不是功能缺失而是一系列你以为不用管、其实绕不开的部署问题。本文基于仓库源码逐层拆解这些坑重点回答一个问题在本地把 Cloudflare OS 跑起来之前你需要先接受哪些约束、补齐哪些配置。先认清差异本地部署不是换台服务器先看 README 里一张被很多人忽略的表格它把 Cloudflare OS 和传统操作系统的概念做了映射传统 OSCloudflare OS仓库中的对应物kernelworkshop-backendpackages/workshop-backenddevice driversgatekeeper-*packages/gatekeeper-*shellworkshop-frontendpackages/workshop-frontendprocessesgadgets每个 gadget 是独立的 Dynamic Worker Facetexecutablesblueprintspackages/bundled-blueprints这张表的关键信息藏在kernel那一格Cloudflare OS 的内核不是一个普通 Node 服务而是一组在 workerdWorkers 运行时里运行的 Worker。pnpm run-local的执行路径scripts/run-local.ts会先跑typed-storage和前端构建再通过 scripts/run-dev-server.ts 拉起一个多配置的wrangler dev把 workshop-backend 和所有 gatekeeper 包作为独立 Worker 一起启动。这意味着两件事本地部署的运行环境就是 workerd不是 Node 也不是 Docker 里随便装的进程。README 里 Deploy to your own server using workerd 一节明确写着COMING SOON——官方工具链还没有为在自己的服务器上部署 workerd准备好文档和脚本只建议有冒险精神的人去读 workerd 的底层配置文档。数据和配置默认落在本地目录。README 注明本地运行的数据存放在.wrangler子目录下启动脚本在内存中生成wrangler.dev.jsonc系列临时配置仓库里所有wrangler.jsonc都是由 scripts/generate-worker-configs.ts 从 TypeScript 配置生成的。所以第一个认知要纠正Cloudflare OS 的私有化部署目前只有一条成熟路径——在 workerd 上自托管而不是部署到任意云厂商的容器平台。搞清楚这一点后面的坑才有讨论的基础。坑一运行时版本与尖端特性是硬依赖Cloudflare OS 不是恰好跑在 Workers 上而是深度绑定 Workers 运行时正在演进的新特性。README 自己承认Dynamic Workers、Facets 以及若干其他特性是专门为支持 Cloudflare OS 而加入运行时的。具体体现为每个 workspace 是一个 Durable Object每个 gadget 跑在一个 Dynamic Worker Facet 里Gatekeeper 也会向 workspace 安装 facet 来管理对远程服务的访问backend 的 packages/workshop-backend/wrangler.jsonc 里声明了worker_loaders绑定、SQLite DO 迁移UserDurableObject、OverseerDurableObject等、allow_irrevocable_stub_storage、global_fetch_strictly_public等 compatibility flags——这些都是较新的运行时能力集成测试文档 docs/integration-testing.md 特别提醒wrangler 和 miniflare 的版本是耦合的pnpm workspace 的 catalog 把 miniflare 精确锁定到 wrangler 依赖的预发布版本两者必须一起升级让它们漂移会装出第二套运行时栈。私有化部署的直接影响是你不能随便挑一个 workerd 版本。Dynamic Workers、Facets、Worker Loaders 这些特性只在较新的 workerd 里可用而本地wrangler dev拉起的 workerd 由 wrangler 决定。一旦你想脱离 wrangler、手写 workerd 配置README 建议的冒险路径你就要自己保证运行时版本覆盖所有这些特性并且要为每个 Worker 手工维护 entrypoint 映射、service binding 和 DO 迁移——这正是官方迟迟不给文档的原因。另外一个容易忽略的版本坑所有wrangler.jsonc都标注由 generate-worker-configs.ts 生成不要手改pnpm configs:check会校验生成结果。想自定义部署拓扑比如只部署部分 Gatekeeper正确做法是改 cloudflare.config.ts 再重新生成而不是直接编辑 JSON。坑二LLM 接入的半云依赖比想象中深Cloudflare OS 的多模型能力并不等于自带模型网关。阅读 packages/workshop-backend/src/env.d.ts 可以看到backend 的环境变量里有一整族CF_AI_GATEWAY*配置CF_AI_GATEWAY开启网关模式把所有 provider 的请求路由到 Cloudflare AI GatewayCF_AI_GATEWAY_ACCOUNT_ID是必需的传输方式二选一WORKERS_AIbinding预认证、免 token但只对 Gateway 与 Worker 同账号有效或CF_AI_GATEWAY_API_TOKENgoogleprovider 无论如何都需要 API token因为它拒绝 binding 的 fetch。而 docs/ai-gateway-billing.md 进一步揭示免费的每日限额 Cloudflare 积分充值流程ENABLE_CLOUDFLARE_LIMITStrue把计费绑死在 Cloudflare 账号体系上——OAuth 端点、scope 直接硬编码在 packages/gatekeeper-cloudflare/src/oauth.ts 里dash.cloudflare.com/oauth2/*scopes 含aig.read aig.run aig.write。也就是说这套免费额度 BYOK 充值玩法天生是云端的私有化部署要么关掉它默认就是关的要么接受用户流量经过 Cloudflare 平台。真正隐蔽的坑在这里WORKERS_AIbinding 不只是 AI 网关的传输通道它还承担webFetch 工具的 document-to-Markdown 转换。文档明确警告WORKERS_AI对每个发布版本的 backend 都是硬编码依赖移除它会直接弄坏网页抓取转换而不仅仅是网关传输。也就是说即使你打算完全走用户自带模型 keyBYOK路线为了让 Agent 能读网页转 Markdown你仍然需要一个可用的 AI 推理通道。对私有化部署的现实结论LLM 这一层自带一个推理入口是硬需求——要么部署一个可以放进WORKERS_AI等价位置的推理服务要么接受 webFetch 文档转换不可用。这还没算上CF_AI_GATEWAY_PROVIDERS管理在/admin的 Models 标签页开关 provider而非环境变量这类运维细节。坑三每一个 Gatekeeper 都要你亲手注册一个 OAuth App这是本地体验最容易卡死的一环。Cloudflare OS 的价值一半在 Gatekeeper——每个外部服务一个独立 Worker负责 OAuth、窄权限、审计日志和人工审批。但每个 Gatekeeper 都需要对应服务提供方的 OAuth 客户端凭据而且很多服务方故意不让这件事变容易README 原话intended audience for OAuth is developers。以 GitHub 为例packages/gatekeeper-github/README.md 列出了几个经典翻车现场必须用 GitHub OAuth App不能用 GitHub App。OAuth App 才 honorscope参数才能实现登录只要最小 scope、连接时才要完整 scopeGitHub Appclient id 以Iv…开头会忽略 scope并且读不到邮箱Resource not accessible by integration除非单独授予 Email addresses 权限。redirect_uri_mismatch回调地址必须精确等于http://localhost:8787/gatekeeper/github/oauth无尾斜杠、本地用http而非https。bad_verification_code授权码过期或已被使用。Not configured 页面CLIENT_ID/CLIENT_SECRET缺失——需要packages/gatekeeper-github/.env存在且包含两个值然后重启 dev server。2026 年 8 月之后注册的 OAuth App 默认开启8 小时过期 tokenGatekeeper 支持自动刷新但刷新 token 本身被拒闲置六个月或已撤销时只能重连。GitLab 的坑更典型packages/gatekeeper-gitlab/README.md 说明 GitLab 的访问 token 只有两小时寿命靠单次使用、每次刷新都轮换的 refresh token 续命而自托管 GitLab 实例如果放在 Cloudflare Access 后面还需要为 Worker 配置 service token且 Access 应用必须在/api/v4/*、/oauth/*和/group/project.git/*三条路径上放行——只放行 API 会导致 git 拉取失败。好消息是仓库把 11 个 Gatekeeper 的配置说明都整理好了README.md 的 Configuring external services 一节逐一链接。坏消息是你每接入一个服务就要去该服务后台注册一个 OAuth App并把它填进对应 Gatekeeper 的环境变量。本地开发时 scripts/run-dev-server.ts 会从根目录.dev.vars读取GITHUB_CLIENT_ID、GOOGLE_CLIENT_ID、CLOUDFLARE_OAUTH_CLIENT_ID等共享凭据注入各 Gatekeeper Worker这些文件是 gitignored 的——意味着换台机器部署整套凭据要重配一遍。坑四企业上下文接入合规边界比功能更早到来私有化部署的最大动机通常是数据合规公司文档、代码仓库、内部系统不能出境。Cloudflare OS 专门为此准备了 Context Librarypackages/gatekeeper-context让 Agent 能读到企业上下文。但恰恰是这个组件把合规问题推到了部署第一天。首先是存储依赖。Context Library 支持git-backed collections——把上下文集合镜像成 git 仓库这依赖ARTIFACTSbindingCloudflare Artifacts。看 packages/gatekeeper-context/src/context-api.ts 和 packages/gatekeeper-context/src/context-collection.ts#assertArtifactsAvailable()在 Artifacts 未配置时直接抛 Git-backed Context collections are not enabledcreateContextCollection也拒绝创建 git 源集合。私有化部署若没有 Artifacts 等价物git 同步、git token 这些功能就没了——但这不影响基础的 web 源集合。其次是数据隔离域。Context Library 用 sharing domain 把所有数据按 Workshop 实例命名空间隔离packages/gatekeeper-context/src/domain.ts本地开发用单一dev域。多个 Workshop 可以绑同一个 Gatekeeper 实例靠 domain 防止数据串台——文档坦诚这不是针对恶意 peer 配置的边界只是防止意外混用。私有化部署时每个实例的 domain 命名要自己规划。然后是分享时的最小权限这是这套系统最值得称道的机制也是合规的核心防线。docs/observers.md 定义了observer模型核心不变量一句话如果某个 Gadget 能读到受限制访问的信息那么任何不能直接读到该信息的用户也被禁止与该 Gadget 交互以防止数据泄漏。实现上Bob 打开 Alice 分享的 Gadget 时必须为 Gadget 用到的每个 Gatekeeper 指定一个他自己名下的已连接账号Gatekeeper 校验 Bob 的账号是否具备直接读取该 Gadget 历史读取过的所有信息的权限不通过就拒绝打开。每次打开都会重新校验。更细的机制包括containsRestrictedData标记后 workspace 进入受限模式——禁止 web 抓取每个动作都必须人工审批自动审批规则被挂起ownerInvitesOnly标记后只有 owner 的直接授权有效分享链接、转授权全部失效已有用户会被踢出各 Gatekeeper 的观测策略分 A/B/C/D 四档docs/observers.md 第 9 节Gmail 邮箱、ZoomInfo 账号这类宽绑定直接拒绝所有协作者策略 AGitHub 仓库、Google Doc 这类按资源 ACL 校验策略 BBigQuery、Notion workspace 这类跟踪实际访问的数据集再逐个校验策略 C。对私有化部署的含义很直接接入企业上下文和把上下文分享出去是两套不同的合规问题。前者要解决存储与数据出境后者要预先设计好协作边界——如果你的团队依赖分享链接协作ownerInvitesOnly一开这套协作模式立刻失效而分享到 Gmail 邮箱的 Gadget从机制上就不允许任何协作者打开。坑五会话与通知流程里隐藏的云端依赖最后这组坑藏得最深因为它们平时不报错只在特定流程触发时才暴露。第一个是PUBLIC_BASE_URL。OAuth 登录/连接流程docs/oauth-signin.md、docs/connect-handoff.md实现了一套精致的防钓鱼机制connect/sign-in URL 是bearer capability任何人打开它都能完成流程所以系统引入了 ticket nonce 双重校验——ticket 是 256 位随机数只存 SHA-256 哈希、单次使用、两分钟有效nonce 写在弹窗自身的 sessionStorage 里只有同时持有两者才能完成。而 ticket 的targetOrigin只从PUBLIC_BASE_URL读取未设置时直接 fail closeddocs/connect-handoff.md 原话fails closed when it is unset. No request header is consulted。本地开发时 scripts/run-dev-server.ts 会自动把它设为http://localhost:3000dev 模式或http://localhost:8787run-local 模式但一旦换域名、换端口、走反向代理所有 OAuth 回调地址/gatekeeper/vendor/oauth和 handoff 页面都必须随之改而 OAuth App 后台注册的回调 URL 也必须是同一份——三处不一致就会遇到Pop-up blocked、This link isnt valid、Could not complete the connection这些 docs/connect-handoff.md 里逐一列出的用户可见错误。第二个是推送通知。packages/workshop-backend/src/env.d.ts 里声明了四个通知相关变量NOTIFICATION_SERVICE_URL、CFOS_INSTALL_ID、CFOS_INSTALL_KEY_ID、CFOS_INSTALL_PRIVATE_KEY——由 Cloudflare 的部署服务在安装时注入用于把推送投递到 Cloudflare 运营的通知服务。文档 docs/notifications.md 明确任何一个缺失推送就不可用通知只能到达当前打开着的浏览器标签页。私有化部署没有这套注入等于默认放弃了站外推送。第三个是BROWSERbinding。backend 用它渲染 Gadget 导出packages/workshop-backend/src/gadget-export.ts但 packages/workshop-backend/src/env.d.ts 特意注明Self-hosted deployments may omit the binding使用处都做了 null-check——这是仓库里少有的、明确为自托管留了退路的依赖。同样可选的还有产品分析管道PRODUCT_ANALYTICS和前端错误上报FRONTEND_ERROR_REPORTER缺失时优雅降级。落地检查清单把上面五个坑浓缩成一张部署前的自检表运行时确认 workerd 版本覆盖 Dynamic Workers / Facets / Worker Loaderswrangler 与 miniflare 必须一起升级别让它们漂移出两套栈改部署拓扑走cloudflare.config.ts再pnpm configs:generate。LLM 通道决定用 AI Gateway 模式还是 BYOK无论如何准备一个可用的推理入口来支撑 webFetch 的 Markdown 转换googleprovider 永远需要 API token。OAuth按 README.md 的 Gatekeeper 清单逐个注册 OAuth AppGitHub 用 OAuth App 而非 GitHub App回调 URL 精确匹配PUBLIC_BASE_URL/gatekeeper/vendor/oauthGitLab 记得处理两小时 token 和 Access service token 的三路径放行。上下文与合规Context Library 的 git 集合依赖 Artifacts没有就只用 web 集合规划好 sharing domain向团队讲清楚 observer 校验、containsRestrictedData和ownerInvitesOnly对协作方式的影响。部署形态PUBLIC_BASE_URL是 OAuth 与 handoff 流程的单一事实来源域名/端口/反代变更要三处同步通知服务缺失可接受但要提前告知用户BROWSER绑定可省略。Cloudflare OS 的定位决定了它的私有化部署不是拷贝一份代码换个平台而是在 workerd 上复刻一个 Workers 运行时生态的子集。好消息是仓库把绝大多数依赖都做成了可配置、可降级null-check、可选 binding、默认关闭的云功能坏消息是没有哪个坑会主动告诉你它存在——它们都藏在配置文件的默认值里。跑起来之前把这五个问题想清楚你的 Your Company OS 才不会在第一周就变成 Your Company 的运维事故。【免费下载链接】cloudflare-osAgent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-os创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
私有化部署 Cloudflare OS本地跑起来之前的五个坑【免费下载链接】cloudflare-osAgent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-osCloudflare OS 开源之后不少团队的第一反应是把公司上下文搬进一个由 Agent 驱动的操作系统听起来很诱人但数据要留在自己手里那就私有化部署吧。仓库 README 的开头也确实是这么许诺的——pnpm run-local一条命令整个栈在 wrangler 和 workerd 上本地跑起来然后访问 http://localhost:8787 就能体验。但能跑和跑好之间隔着一条很宽的沟。这个项目本质上是 Cloudflare Workers 平台能力的集大成者Durable Objects、Dynamic Workers、Facets、Worker Loaders、KV、R2、SQLite DO、Browser Rendering……其中好几个运行时特性是 Cloudflare 为了支撑 Cloudflare OS 才专门加入的。把这样一套东西搬离云端最先撞上的不是功能缺失而是一系列你以为不用管、其实绕不开的部署问题。本文基于仓库源码逐层拆解这些坑重点回答一个问题在本地把 Cloudflare OS 跑起来之前你需要先接受哪些约束、补齐哪些配置。先认清差异本地部署不是换台服务器先看 README 里一张被很多人忽略的表格它把 Cloudflare OS 和传统操作系统的概念做了映射传统 OSCloudflare OS仓库中的对应物kernelworkshop-backendpackages/workshop-backenddevice driversgatekeeper-*packages/gatekeeper-*shellworkshop-frontendpackages/workshop-frontendprocessesgadgets每个 gadget 是独立的 Dynamic Worker Facetexecutablesblueprintspackages/bundled-blueprints这张表的关键信息藏在kernel那一格Cloudflare OS 的内核不是一个普通 Node 服务而是一组在 workerdWorkers 运行时里运行的 Worker。pnpm run-local的执行路径scripts/run-local.ts会先跑typed-storage和前端构建再通过 scripts/run-dev-server.ts 拉起一个多配置的wrangler dev把 workshop-backend 和所有 gatekeeper 包作为独立 Worker 一起启动。这意味着两件事本地部署的运行环境就是 workerd不是 Node 也不是 Docker 里随便装的进程。README 里 Deploy to your own server using workerd 一节明确写着COMING SOON——官方工具链还没有为在自己的服务器上部署 workerd准备好文档和脚本只建议有冒险精神的人去读 workerd 的底层配置文档。数据和配置默认落在本地目录。README 注明本地运行的数据存放在.wrangler子目录下启动脚本在内存中生成wrangler.dev.jsonc系列临时配置仓库里所有wrangler.jsonc都是由 scripts/generate-worker-configs.ts 从 TypeScript 配置生成的。所以第一个认知要纠正Cloudflare OS 的私有化部署目前只有一条成熟路径——在 workerd 上自托管而不是部署到任意云厂商的容器平台。搞清楚这一点后面的坑才有讨论的基础。坑一运行时版本与尖端特性是硬依赖Cloudflare OS 不是恰好跑在 Workers 上而是深度绑定 Workers 运行时正在演进的新特性。README 自己承认Dynamic Workers、Facets 以及若干其他特性是专门为支持 Cloudflare OS 而加入运行时的。具体体现为每个 workspace 是一个 Durable Object每个 gadget 跑在一个 Dynamic Worker Facet 里Gatekeeper 也会向 workspace 安装 facet 来管理对远程服务的访问backend 的 packages/workshop-backend/wrangler.jsonc 里声明了worker_loaders绑定、SQLite DO 迁移UserDurableObject、OverseerDurableObject等、allow_irrevocable_stub_storage、global_fetch_strictly_public等 compatibility flags——这些都是较新的运行时能力集成测试文档 docs/integration-testing.md 特别提醒wrangler 和 miniflare 的版本是耦合的pnpm workspace 的 catalog 把 miniflare 精确锁定到 wrangler 依赖的预发布版本两者必须一起升级让它们漂移会装出第二套运行时栈。私有化部署的直接影响是你不能随便挑一个 workerd 版本。Dynamic Workers、Facets、Worker Loaders 这些特性只在较新的 workerd 里可用而本地wrangler dev拉起的 workerd 由 wrangler 决定。一旦你想脱离 wrangler、手写 workerd 配置README 建议的冒险路径你就要自己保证运行时版本覆盖所有这些特性并且要为每个 Worker 手工维护 entrypoint 映射、service binding 和 DO 迁移——这正是官方迟迟不给文档的原因。另外一个容易忽略的版本坑所有wrangler.jsonc都标注由 generate-worker-configs.ts 生成不要手改pnpm configs:check会校验生成结果。想自定义部署拓扑比如只部署部分 Gatekeeper正确做法是改 cloudflare.config.ts 再重新生成而不是直接编辑 JSON。坑二LLM 接入的半云依赖比想象中深Cloudflare OS 的多模型能力并不等于自带模型网关。阅读 packages/workshop-backend/src/env.d.ts 可以看到backend 的环境变量里有一整族CF_AI_GATEWAY*配置CF_AI_GATEWAY开启网关模式把所有 provider 的请求路由到 Cloudflare AI GatewayCF_AI_GATEWAY_ACCOUNT_ID是必需的传输方式二选一WORKERS_AIbinding预认证、免 token但只对 Gateway 与 Worker 同账号有效或CF_AI_GATEWAY_API_TOKENgoogleprovider 无论如何都需要 API token因为它拒绝 binding 的 fetch。而 docs/ai-gateway-billing.md 进一步揭示免费的每日限额 Cloudflare 积分充值流程ENABLE_CLOUDFLARE_LIMITStrue把计费绑死在 Cloudflare 账号体系上——OAuth 端点、scope 直接硬编码在 packages/gatekeeper-cloudflare/src/oauth.ts 里dash.cloudflare.com/oauth2/*scopes 含aig.read aig.run aig.write。也就是说这套免费额度 BYOK 充值玩法天生是云端的私有化部署要么关掉它默认就是关的要么接受用户流量经过 Cloudflare 平台。真正隐蔽的坑在这里WORKERS_AIbinding 不只是 AI 网关的传输通道它还承担webFetch 工具的 document-to-Markdown 转换。文档明确警告WORKERS_AI对每个发布版本的 backend 都是硬编码依赖移除它会直接弄坏网页抓取转换而不仅仅是网关传输。也就是说即使你打算完全走用户自带模型 keyBYOK路线为了让 Agent 能读网页转 Markdown你仍然需要一个可用的 AI 推理通道。对私有化部署的现实结论LLM 这一层自带一个推理入口是硬需求——要么部署一个可以放进WORKERS_AI等价位置的推理服务要么接受 webFetch 文档转换不可用。这还没算上CF_AI_GATEWAY_PROVIDERS管理在/admin的 Models 标签页开关 provider而非环境变量这类运维细节。坑三每一个 Gatekeeper 都要你亲手注册一个 OAuth App这是本地体验最容易卡死的一环。Cloudflare OS 的价值一半在 Gatekeeper——每个外部服务一个独立 Worker负责 OAuth、窄权限、审计日志和人工审批。但每个 Gatekeeper 都需要对应服务提供方的 OAuth 客户端凭据而且很多服务方故意不让这件事变容易README 原话intended audience for OAuth is developers。以 GitHub 为例packages/gatekeeper-github/README.md 列出了几个经典翻车现场必须用 GitHub OAuth App不能用 GitHub App。OAuth App 才 honorscope参数才能实现登录只要最小 scope、连接时才要完整 scopeGitHub Appclient id 以Iv…开头会忽略 scope并且读不到邮箱Resource not accessible by integration除非单独授予 Email addresses 权限。redirect_uri_mismatch回调地址必须精确等于http://localhost:8787/gatekeeper/github/oauth无尾斜杠、本地用http而非https。bad_verification_code授权码过期或已被使用。Not configured 页面CLIENT_ID/CLIENT_SECRET缺失——需要packages/gatekeeper-github/.env存在且包含两个值然后重启 dev server。2026 年 8 月之后注册的 OAuth App 默认开启8 小时过期 tokenGatekeeper 支持自动刷新但刷新 token 本身被拒闲置六个月或已撤销时只能重连。GitLab 的坑更典型packages/gatekeeper-gitlab/README.md 说明 GitLab 的访问 token 只有两小时寿命靠单次使用、每次刷新都轮换的 refresh token 续命而自托管 GitLab 实例如果放在 Cloudflare Access 后面还需要为 Worker 配置 service token且 Access 应用必须在/api/v4/*、/oauth/*和/group/project.git/*三条路径上放行——只放行 API 会导致 git 拉取失败。好消息是仓库把 11 个 Gatekeeper 的配置说明都整理好了README.md 的 Configuring external services 一节逐一链接。坏消息是你每接入一个服务就要去该服务后台注册一个 OAuth App并把它填进对应 Gatekeeper 的环境变量。本地开发时 scripts/run-dev-server.ts 会从根目录.dev.vars读取GITHUB_CLIENT_ID、GOOGLE_CLIENT_ID、CLOUDFLARE_OAUTH_CLIENT_ID等共享凭据注入各 Gatekeeper Worker这些文件是 gitignored 的——意味着换台机器部署整套凭据要重配一遍。坑四企业上下文接入合规边界比功能更早到来私有化部署的最大动机通常是数据合规公司文档、代码仓库、内部系统不能出境。Cloudflare OS 专门为此准备了 Context Librarypackages/gatekeeper-context让 Agent 能读到企业上下文。但恰恰是这个组件把合规问题推到了部署第一天。首先是存储依赖。Context Library 支持git-backed collections——把上下文集合镜像成 git 仓库这依赖ARTIFACTSbindingCloudflare Artifacts。看 packages/gatekeeper-context/src/context-api.ts 和 packages/gatekeeper-context/src/context-collection.ts#assertArtifactsAvailable()在 Artifacts 未配置时直接抛 Git-backed Context collections are not enabledcreateContextCollection也拒绝创建 git 源集合。私有化部署若没有 Artifacts 等价物git 同步、git token 这些功能就没了——但这不影响基础的 web 源集合。其次是数据隔离域。Context Library 用 sharing domain 把所有数据按 Workshop 实例命名空间隔离packages/gatekeeper-context/src/domain.ts本地开发用单一dev域。多个 Workshop 可以绑同一个 Gatekeeper 实例靠 domain 防止数据串台——文档坦诚这不是针对恶意 peer 配置的边界只是防止意外混用。私有化部署时每个实例的 domain 命名要自己规划。然后是分享时的最小权限这是这套系统最值得称道的机制也是合规的核心防线。docs/observers.md 定义了observer模型核心不变量一句话如果某个 Gadget 能读到受限制访问的信息那么任何不能直接读到该信息的用户也被禁止与该 Gadget 交互以防止数据泄漏。实现上Bob 打开 Alice 分享的 Gadget 时必须为 Gadget 用到的每个 Gatekeeper 指定一个他自己名下的已连接账号Gatekeeper 校验 Bob 的账号是否具备直接读取该 Gadget 历史读取过的所有信息的权限不通过就拒绝打开。每次打开都会重新校验。更细的机制包括containsRestrictedData标记后 workspace 进入受限模式——禁止 web 抓取每个动作都必须人工审批自动审批规则被挂起ownerInvitesOnly标记后只有 owner 的直接授权有效分享链接、转授权全部失效已有用户会被踢出各 Gatekeeper 的观测策略分 A/B/C/D 四档docs/observers.md 第 9 节Gmail 邮箱、ZoomInfo 账号这类宽绑定直接拒绝所有协作者策略 AGitHub 仓库、Google Doc 这类按资源 ACL 校验策略 BBigQuery、Notion workspace 这类跟踪实际访问的数据集再逐个校验策略 C。对私有化部署的含义很直接接入企业上下文和把上下文分享出去是两套不同的合规问题。前者要解决存储与数据出境后者要预先设计好协作边界——如果你的团队依赖分享链接协作ownerInvitesOnly一开这套协作模式立刻失效而分享到 Gmail 邮箱的 Gadget从机制上就不允许任何协作者打开。坑五会话与通知流程里隐藏的云端依赖最后这组坑藏得最深因为它们平时不报错只在特定流程触发时才暴露。第一个是PUBLIC_BASE_URL。OAuth 登录/连接流程docs/oauth-signin.md、docs/connect-handoff.md实现了一套精致的防钓鱼机制connect/sign-in URL 是bearer capability任何人打开它都能完成流程所以系统引入了 ticket nonce 双重校验——ticket 是 256 位随机数只存 SHA-256 哈希、单次使用、两分钟有效nonce 写在弹窗自身的 sessionStorage 里只有同时持有两者才能完成。而 ticket 的targetOrigin只从PUBLIC_BASE_URL读取未设置时直接 fail closeddocs/connect-handoff.md 原话fails closed when it is unset. No request header is consulted。本地开发时 scripts/run-dev-server.ts 会自动把它设为http://localhost:3000dev 模式或http://localhost:8787run-local 模式但一旦换域名、换端口、走反向代理所有 OAuth 回调地址/gatekeeper/vendor/oauth和 handoff 页面都必须随之改而 OAuth App 后台注册的回调 URL 也必须是同一份——三处不一致就会遇到Pop-up blocked、This link isnt valid、Could not complete the connection这些 docs/connect-handoff.md 里逐一列出的用户可见错误。第二个是推送通知。packages/workshop-backend/src/env.d.ts 里声明了四个通知相关变量NOTIFICATION_SERVICE_URL、CFOS_INSTALL_ID、CFOS_INSTALL_KEY_ID、CFOS_INSTALL_PRIVATE_KEY——由 Cloudflare 的部署服务在安装时注入用于把推送投递到 Cloudflare 运营的通知服务。文档 docs/notifications.md 明确任何一个缺失推送就不可用通知只能到达当前打开着的浏览器标签页。私有化部署没有这套注入等于默认放弃了站外推送。第三个是BROWSERbinding。backend 用它渲染 Gadget 导出packages/workshop-backend/src/gadget-export.ts但 packages/workshop-backend/src/env.d.ts 特意注明Self-hosted deployments may omit the binding使用处都做了 null-check——这是仓库里少有的、明确为自托管留了退路的依赖。同样可选的还有产品分析管道PRODUCT_ANALYTICS和前端错误上报FRONTEND_ERROR_REPORTER缺失时优雅降级。落地检查清单把上面五个坑浓缩成一张部署前的自检表运行时确认 workerd 版本覆盖 Dynamic Workers / Facets / Worker Loaderswrangler 与 miniflare 必须一起升级别让它们漂移出两套栈改部署拓扑走cloudflare.config.ts再pnpm configs:generate。LLM 通道决定用 AI Gateway 模式还是 BYOK无论如何准备一个可用的推理入口来支撑 webFetch 的 Markdown 转换googleprovider 永远需要 API token。OAuth按 README.md 的 Gatekeeper 清单逐个注册 OAuth AppGitHub 用 OAuth App 而非 GitHub App回调 URL 精确匹配PUBLIC_BASE_URL/gatekeeper/vendor/oauthGitLab 记得处理两小时 token 和 Access service token 的三路径放行。上下文与合规Context Library 的 git 集合依赖 Artifacts没有就只用 web 集合规划好 sharing domain向团队讲清楚 observer 校验、containsRestrictedData和ownerInvitesOnly对协作方式的影响。部署形态PUBLIC_BASE_URL是 OAuth 与 handoff 流程的单一事实来源域名/端口/反代变更要三处同步通知服务缺失可接受但要提前告知用户BROWSER绑定可省略。Cloudflare OS 的定位决定了它的私有化部署不是拷贝一份代码换个平台而是在 workerd 上复刻一个 Workers 运行时生态的子集。好消息是仓库把绝大多数依赖都做成了可配置、可降级null-check、可选 binding、默认关闭的云功能坏消息是没有哪个坑会主动告诉你它存在——它们都藏在配置文件的默认值里。跑起来之前把这五个问题想清楚你的 Your Company OS 才不会在第一周就变成 Your Company 的运维事故。【免费下载链接】cloudflare-osAgent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems.项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-os创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
