企业官网建设流程全解析

• 可观测性
• 运维
• 后端

导读

本文以 Pulse 仓库发布管控记录 cloud-hosted-tier-runtime-readiness-2026-03-13.md 为主体，系统梳理"Cloud Hosted Tier"（托管云租户层）作为真实运行层级进入发布流程时所依赖的验证方法、自动化测试基线、手工演练步骤与门禁评估结论。读者将掌握：如何在本机以 hosted 模式拉起真实 Pulse 实例并验证多租户注册、魔法链接登录、平台管理员控制面、租户账单状态与租户级授权发放的完整链路，以及理解发布门禁证据分级（本地预演 vs 真实外部 E2E）的判定逻辑。全文结合internal/hosted、internal/api、internal/cloudcp等源码与测试给出实现级佐证。

一、记录背景：发布门禁与断言编号

该文档是一份发布管控（release-control）内部记录，服务于名为cloud-hosted-tier-runtime-readiness的门禁（Gate），对应断言编号RA11。其核心命题是：

Hosted Pulse（托管版 Pulse）能否在真实运行的 hosted 模式运行时（runtime）上被当作一个"真实层级"（real tier）进入，而不只是在 signup 与 billing 的处理器级测试中被模拟出来。

记录日期为2026-03-13，执行环境为：

• 运行实例：本机 localhost 上的 hosted 模式 Pulse，地址http://127.0.0.1:17771；
• 持久化数据目录：tmp/manual-hosted-runtime-20260313/data（对应仓库内tmp/manual-hosted-runtime-20260313这一预演数据目录）；
• 平台管理员：admin；
• 预演期间创建的托管租户：fa0b5ad9-0bcf-47ba-8104-e6d71f0d3752，注册邮箱hosted-rc-20260313@example.com；
• 门禁重开后的复验租户：fc6c9ffa-f100-46a2-b5e6-349dba526469，注册邮箱hosted-rc-rerun-20260313-0942@example.com。

这组"同一实例 + 同一数据目录 + 两轮注册"的编排，是为了证明 hosted 运行时的能力不仅存在于一次性内存测试中，而是能够在持久化状态上反复重启、复现、延续。

二、自动化证明基线：三层测试组合

记录中的 Automated Proof Baseline 由三条命令构成，覆盖 Go 后端与前端 React 组件两层：

# 1) API 层：托管生命周期、组织管理员处理器、注册成功/校验失败/门禁/限流/清理/关闭，以及 Stripe Webhook go test ./internal/api -run 'TestHostedLifecycle|TestHostedOrgAdminHandlers|TestHostedSignupSuccess|TestHostedSignupValidationFailures|TestHostedSignupHostedModeGate|TestHostedSignupRateLimit|TestHostedSignupRateLimit_NoProvisioningSideEffects|TestHostedSignupCleanupOnRBACFailure|TestHostedSignupFailsClosedWithoutPublicURL|TestStripeWebhook_' -count=1 # 2) 托管核心包：cloudcp（云控制面）与 hosted（租户供应/回收） go test ./internal/cloudcp/... ./internal/hosted/... -count=1 # 3) 前端：注册页与两类账单管理面板 cd frontend-modern && npx vitest run src/pages/__tests__/HostedSignup.test.tsx src/components/Settings/__tests__/BillingAdminPanel.test.tsx src/components/Settings/__tests__/OrganizationBillingPanel.test.tsx

这三条命令的覆盖层次在源码中可以逐一对应：

• TestHostedLifecycle位于 internal/api/hosted_lifecycle_integration_test.go，其子用例Signup_SeedsTrialBillingState_ForBillingAdmin验证注册后通过config.NewFileBillingStore(baseDir)落盘生成subscription_state=trial、plan_version=cloud_trial的账单状态，且不发放 quickstart 积分；Signup_Billing_Entitlements_Flow则验证从注册到账单状态再到租户授权（entitlements）的端到端数据流；
• TestHostedSignupSuccess等注册相关测试位于 internal/api/hosted_signup_handlers_test.go，覆盖成功注册（返回202、响应中省略org_id与user_id以避免枚举探测）、邮箱格式/组织名校验失败（返回400）、hosted 模式门禁、注册限流及其"无供应副作用"约束、RBAC 失败时的清理回滚、以及未配置 Public URL 时的失败关闭（fails closed）；
• TestHostedOrgAdminHandlers位于 internal/api/hosted_org_admin_handlers_test.go，其中TestHostedOrganizationsList_HostedModeGate验证非 hosted 模式下组织列表接口被门禁拦截，TestHostedOrganizationsList_ReturnsSummaries验证 hosted 模式下返回租户摘要。

记录结果：三层基线全部pass。

三、手工演练：在真实 hosted 运行时上验证完整租户链路

自动化测试之外，记录强调这次演练刻意使用了真实的pulse二进制运行在本机 HTTP 表面上，而非只跑处理器级测试（handler-only tests）。演练分六个步骤：

1. 冷启动 + 认证种子 + hosted 模式重启

先以普通模式启动干净的 localhost 实例，执行 Quick Security Setup，确认认证与 API Token 状态持久化到tmp/manual-hosted-runtime-20260313/data/.env与api_tokens.json；随后针对同一数据目录以 hosted 模式重启同一实例。

这一步的设计意图记录在文档 Notes 中：认证种子在 hosted 重启之前注入，是为了让 hosted 运行时的证明覆盖"持久化的认证与运行时连续性"，而不是一次性内存测试。

2. 认证边界复检

重启后的 hosted 实例必须在特权表面上强制认证：

• GET /api/security/status→requiresAuth=true、hasAuthentication=true、apiTokenConfigured=true；
• 匿名GET /api/hosted/organizations→401 Authentication required；
• 匿名GET /api/admin/orgs/fa0b5ad9-0bcf-47ba-8104-e6d71f0d3752/billing-state→401 Authentication required。

也就是说：hosted 运行时仍然保持"特权面封闭"，匿名访问被拒，但平台管理员自身仍可正常使用这些控制面。

3. 真实托管注册

对 live hosted 表面执行：

POST /api/public/signup # body: {"email":"hosted-rc-20260313@example.com","org_name":"Hosted RC 20260313"}

返回201 Created，并携带：

{"org_id":"fa0b5ad9-0bcf-47ba-8104-e6d71f0d3752","message":"Check your email for a magic link to finish signing in."}

注册路由在 internal/cloudcp/routes.go 中由publicSignupLimiter.Middleware包裹，处理器为publicCloudSignupHandlers.HandlePublicSignup；其底层租户供应逻辑见 internal/hosted/provisioner.go 中的ProvisionHostedSignup：先ensureReady→ 归一化与校验请求 → 按 owner 邮箱查重（存在则复用已有租户并返回existing状态）→ 生成新 orgID 并调用createOrganization完成落盘。

4. 注册后公开认证通道

POST /api/public/magic-link/request # body: {"email":"hosted-rc-20260313@example.com"}

返回200，payload：

{"success":true,"message":"If that email is registered, you'll receive a magic link shortly."}

注意该响应刻意不区分邮箱是否注册（统一提示语），避免邮箱枚举泄露。该通道在 internal/cloudcp/routes.go 中注册为/api/public/magic-link/request，即使公共注册可能处于 prelaunch 门禁状态，也为存量托管账号保持可用。

5. 平台管理员控制面可见性

以admin认证调用GET /api/hosted/organizations，返回200，租户列表同时包含default与新租户fa0b5ad9-...；新租户摘要字段为display_name="Hosted RC 20260313"、owner_user_id="hosted-rc-20260313@example.com"。

6. 租户账单/管理与授权一致性

• GET /api/admin/orgs/fa0b5ad9-.../billing-state（admin 认证）→200，subscription_state=trial、plan_version=cloud_trial，并带完整的托管试用能力集（capabilities）；
• GET /api/license/entitlements，同时携带X-Pulse-Org-ID与X-Org-ID两个请求头指向该租户 →200，返回hosted_mode=true、valid=true、subscription_state=trial、plan_version=cloud_trial、tier=pro、upgrade_reasons=[]。

第 7 步是整个演练的关键判定点：租户级授权落地到 hosted 运行时状态，而不是回退到自托管（self-hosted）的"过期/免费"姿势。这直接验证了"托管租户的授权路径正确"这一断言。

四、门禁重开后的复验：持久化运行时的可重现性

门禁在演练后被重开（gate reopen），记录进行了第二轮完整复验，环境与第一轮相同：

1. 针对同一持久化数据目录重新拉起 hosted 运行时，确认认证与 Token 状态仍然加载成功；
2. 认证边界三个探测全部复现（requiresAuth=true、两个匿名请求仍为401）；
3. 以新邮箱hosted-rc-rerun-20260313-0942@example.com与组织名Hosted RC Rerun 20260313 0942执行新注册 → 再次201 Created，返回新租户fc6c9ffa-f100-46a2-b5e6-349dba526469；
4. magic-link 请求再次返回200与相同提示语；
5. GET /api/hosted/organizations列表现在包含default、第一轮租户与第二轮租户三个条目；
6. 第二轮租户的 billing-state 仍为trial/cloud_trial；
7. 携带X-Pulse-Org-ID/X-Org-ID指向第二轮租户的 entitlements 返回hosted_mode=true、valid=true、trial、cloud_trial、tier=pro、upgrade_reasons=[]；
8. 复验后重跑三命令自动化证明基线，结果仍为pass。

复验的意义在于：同一个持久化 hosted 运行时在门禁重开后产生了相同结果，说明本地 localhost 托管预演是一份有效且可重复的支持证据，而不是一次性巧合。

五、结论评估：为什么门禁仍然 Pending

记录的 Outcome 明确区分了"验证了什么"与"还没验证什么"：

已验证（本地 hosted 运行时）

• Hosted Pulse 可以作为一个真实层级在 live hosted-mode 运行时上进入，而非仅在 signup/billing 测试中被供应；
• 公共注册与 magic-link 请求在同一个同时承载 hosted 运行时/管理面的实例上保持可用；
• 供应完成后，托管账单/管理与租户级授权反映出一致的托管试用状态；
• 注册后的租户路径落在 hosted 授权状态（hosted_mode=true、有效试用态），而非回退到自托管过期/免费姿势；
• 特权托管管理面保持受保护，同时对平台管理员正常可用。

未验证（缺口）

• 该证据仍低于门禁要求的real-external-e2e阈值——它是在 live localhost hosted-mode 运行时上演练的，不是在真实外部托管服务上；
• 因此门禁保持pending，直到同样的流程在真实外部托管层级（real external hosted tier）上被完整演练。

这一"本地证据足够、但门禁不放行"的结论，展示了发布管控中对证据分级的严谨性：本地预演可以证明运行时连续性、授权落点与边界安全，但"真实外部 E2E"才代表对外提供的托管服务在公网环境下的实际表现。

六、源码佐证：关键实现与测试落点

为了让读者能继续深入，这里汇总本文引用的核心证据文件（均为仓库内相对路径）：

需要提醒的是，文档中记录的本地数据目录tmp/manual-hosted-runtime-20260313属于演练时临时产物；若要复现该预演，需按照第三节的步骤自行构建：先启动普通模式实例完成 Quick Security Setup 与 API Token 配置，再针对同一数据目录以 hosted 模式重启，随后按序执行认证边界探测、公共注册、magic-link 请求、管理员租户列表与租户级 entitlements 查询。

七、小结

cloud-hosted-tier-runtime-readiness（RA11）这份记录展示了 Pulse 发布流程中一个典型"运行时就绪度"门禁的完整证据链：自动化基线证明处理器与前端行为，手工演练证明真实二进制 + 持久化数据 + hosted 模式下的运行时连续性，门禁重开复验证明可重现性，最终由证据分级（本地预演 < 真实外部 E2E）决定门禁状态。对需要理解 Pulse 托管多租户架构的读者而言，这也是理解/api/public/signup、/api/public/magic-link/request、/api/hosted/organizations、/api/admin/orgs/{id}/billing-state与/api/license/entitlements这套托管链路如何协同工作的最佳入口。

• 可观测性
• 运维
• 后端