在 CloudBase 云托管上部署后端服务时如何选型…

需要部署 CloudBase Run 后端服务（长连接、自定义运行时、VPC 数据库、Agent、迁移已有应用）或排查容器部署失败时使用。

适用场景

解决思路

1. 先选模式：Function mode 适合快速启动、Node.js 服务模式、内置框架、Agent 流程；Container mode 适合已有容器、任意运行时、自定义系统依赖。
2. 遵循强制运行时规则：Container mode 必须监听注入的 PORT；Function mode 由框架绑定端口，代码绝不能调用 app.listen()。
3. 写任何 CloudBase SDK 调用前先定下凭证门三件事：谁签发（用 manageAppAuth(action="createApiKey", keyType="api_key", keyName="<service>-<env>") 或 CLI tcb env apikey create my-key -e env-xxx，不要从本地 auth.json / .cloudbase/ 取）、怎么注入（经 serverConfig.EnvParams 注入 CLOUDBASE_APIKEY，@cloudbase/node-sdk 自动读取，改环境变量时保留已有键值）、怎么吊销（每服务一把专用 key，记录 keyName 与轮换负责人，下线或轮换时 manageAppAuth(action="deleteApiKey", keyId=...) 并重新部署）。
4. 保持服务无状态，把持久数据放到 DB/存储/缓存；保持依赖与镜像体积小；资源比例遵循 Mem = 2 × CPU。
5. 选型时优先 HTTP 云函数：无状态 HTTP 服务、短生命周期请求、无需自定义系统依赖、有 Dockerfile 但本质是无状态 HTTP 时都选 HTTP 云函数；只有长连接（WebSocket/SSE/服务端推送）、自定义系统依赖/任意语言运行时/稳定独立进程、VPC 内数据库或 Redis 访问、Agent 服务、迁移已有/GitHub/第三方应用或需要常驻进程时才选云托管。
6. 部署前先过数据库访问方式决策门：能用 CloudBase SDK/网关访问的数据一律优先 SDK 路径（CloudBase PG 用 app.rdb()、NoSQL 用 app.database()、对象存储用 app.storage），无需 VpcConf 也无需数据库账号密码；仅迁移已有/GitHub/第三方应用（经典驱动或 ORM 如 mysql2、pg、Prisma、SQLAlchemy、WordPress/Ghost）或需要 SDK 不覆盖的能力（特定 SQL 方言、存储过程、Redis 原生协议）时才走 TCP 直连并完成 references/vpc-and-database.md 全流程。
7. 扫描到 DATABASE_URL / DB 依赖信号时先停下来回答「这个数据访问能不能换成 SDK/网关」，再决定是否进入 VPC checklist，不要默认按 TCP 直连方案往下走。
8. 用正确的工具：读操作用 queryCloudRun，写操作用 manageCloudRun，删除需显式确认并传 force: true，所有本地项目路径用绝对路径 targetPath。
9. 按部署顺序执行：初始化或下载代码 → 全新环境先调 manageCloudRun(action="initEnv", envId=...) 开通云托管（异步、幂等）并轮询 queryCloudRun(action="envStatus") 到 Status=normal → Container mode 校验 Dockerfile → 扫描 DB/缓存依赖信号 → 若需 TCP 数据库访问先完成 VPC checklist → 本地运行（如可用）→ 配置 ingress 访问模型与 egress VpcConf → 第三方镜像先完成五要素文档清单 → 部署并验证详情输出与 DB 连通性 → 失败则走 Container deploy failure SOP。
10. 区分两类日志：云端源码构建（传 targetPath、走 CODING）先 getDeployLog 查构建日志再 getProcessLog 查运行日志；已有镜像部署（传 imageUrl、DeployType=image）跳过 getDeployLog，直接从 detail 或 getDeployRecords 取 latestDeploy.RunId 再 getProcessLog。
11. 撞到「已有部署发布任务运行中」时不要盲目重试或改 Dockerfile/serverConfig：先 queryCloudRun(action="getManageTask") 读 taskId/taskStatus/latestDeployStatus，再隔 20–40 秒两次拉 getProcessLog 确认部署步骤是否推进；任务仍在推进就继续等，任务已结束而 deploy 仍被拒才考虑重试，长时间停在非终态就记录证据不要空转；force=true 只跳过本工具确认提示，不会取消或覆盖服务端已有发布任务。
12. 部署已有镜像时按决策路径：公网匿名可拉取（如 ccr.ccs.tencentyun.com/...、公开 Docker Hub 镜像）直接传 imageUrl；私有/需登录 registry（ghcr.io、私有 ECR/Harbor）先 docker pull → docker tag 到 ccr.ccs.tencentyun.com/<ns>/app:latest → docker login → docker push，再把 CCR 地址作为 imageUrl 传入；docker.io 反复拉取失败时改用 Dockerfile FROM <public-image> + targetPath 源码构建。
13. 镜像部署同样要求环境已开通云托管：新环境首次部署前先 manageCloudRun(action="initEnv", envId=...) 并轮询 envStatus 到 Status=normal。
14. Container 部署失败严格按 SOP 顺序：先查镜像官方文档 → 再查运行日志 → 最后才动配置，禁止一看到 probe failed / deploy_failed 就调 InitialDelaySeconds。
15. 部署前从镜像官方文档确认五要素：启动命令 EntryPoint/Cmd（→ serverConfig.EntryPoint/Cmd）、服务端口（→ serverConfig.Port，不要假设 80/3000 或假设镜像尊重 PORT）、对外监听环境变量（必须 0.0.0.0 而非 127.0.0.1，→ EnvParams）、数据目录挂载（→ serverConfig.VolumesConf）、健康端点（CloudRun readiness 探的是服务端口，不是任意 HTTP path）。
16. 用 getProcessLog 定性失败：隔 20–40 秒两次拉取对比，只有调度/创建步骤（create_eks_*）无容器 stdout 是 Pod 调度中/镜像拉取；同一段启动 banner 或 PID 1 行重复出现是容器启动即退出/重启循环；进程还在但 listen 在 127.0.0.1 或端口 ≠ serverConfig.Port 是端口/绑定地址问题；两次拉取是同一条启动过程往后打日志、banner 不重复才可能是启动慢。
17. 理解 readiness probe 真实机制：先等 N 秒（InitialDelaySeconds），再约每 5 秒探一次服务端口，连续约 30 次全失败才判本次部署失败，窗口约 N+150s；禁止看到 probe failed 就把 N 改成 120，只有两次日志证明同一进程还在一次性初始化（JVM 预热、迁移）且尚未 listen 时才允许调大 N。
18. Supervisor 镜像（s6/tini/supervisord）启动即退出时，PID 1 往往是监督进程而非 HTTP 应用，用两次日志找子进程重启风暴，按镜像 issue 文档 workaround（绝对路径 Cmd、关闭 supervise），不要调探针延迟。
19. 访问配置：Web/公网场景有意开启 PUBLIC ingress 并配合正确认证流程；小程序优先内网直连避免不必要公网暴露；私有 ingress 场景除非产品明确需要否则关闭公网访问；VPC 内数据库/Redis 不能靠 OpenAccessTypes 解决，必须设置 serverConfig.VpcConf 并使用数据库私网地址。
20. OpenAccessTypes 合法值：OA（办公网访问）、PUBLIC（公网访问）、MINIAPP（小程序访问）、VPC（VPC访问）；需要公网 HTTPS 的 Web 应用用 PUBLIC。
21. MinNum: 1 是降低冷启动延迟的推荐默认值；用户明确偏好低成本并接受更多冷启动时，说明权衡后允许降到 0。
22. 最佳实践：尽量用 PRIVATE/VPC 或小程序内网 ingress；TCP 数据库访问时私网 DB URL 必须与 VpcConf 在同一 VPC/地域；密钥和分环境配置用环境变量且只在服务端读取、绝不在 HTTP 响应中返回；部署前后用 queryCloudRun(action="detail") 验证配置；保持启动工作小以减少冷启动影响；Agent 场景用 Agent SDK skill 查协议与适配器细节；冒烟测试返回固定 { "ok": true } / 健康负载，绝不部署 httpbin 或任何反射请求头的服务。
23. 排障提示：访问失败查 ingress 访问类型、域名配置、实例是否缩容到零；部署被「尚未初始化云托管」拦截时先 initEnv 并轮询 envStatus 到 normal，或考虑改用 HTTP 云函数；部署被「已有部署发布任务运行中」拒绝时先 getManageTask 读真实任务状态；部署被接受但版本一直停在 creating 时用 getManageTask 查 latestDeployStatus + taskStatus 再 getProcessLog 查部署阶段步骤，只有日志确实指向代码或配置才改 Dockerfile/serverConfig；本地运行失败记住只有 Function mode 支持本地运行工具；性能问题减少依赖、优化初始化、调整最小实例数；部署成功后 DB/Redis 连接失败几乎总是 VpcConf 缺失或错误、私网地址错误或安全组问题，先按 references/vpc-and-database.md 处理再改应用代码；服务内 CloudBase SDK 调用报凭证缺失/无效说明跳过了凭证门或变量名非官方，用 manageAppAuth(action="createApiKey") 签发、经 EnvParams 注入 CLOUDBASE_APIKEY、重新部署后验证一次真实读取。
24. 确认 handler 绝不回显 x-cloudbase-context、完整请求头或凭证环境变量，不部署 httpbin 式反射服务，遵循 ../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md。
25. 需要时读取配套技能与协议：HTTP 处理器或镜像部署前读敏感运行时数据保护与 Deployment Gate 协议；云函数替代方案读 ../cloud-functions/SKILL.md；Agent SDK 与 AG-UI 读 ../cloudbase-agent/SKILL.md；浏览器调用方 Web 认证读 ../auth-web-cloudbase/SKILL.md；已有应用 + TCP 数据库网络读 references/vpc-and-database.md；容器镜像部署失败/探针/deploy_failed 读 references/image-deploy-troubleshooting.md；服务经 SDK 调 CloudBase 资源读 ../cloud-functions/references/http-function-credentials.md。
26. 引用的同级技能文件缺失时，请用户安装完整 CloudBase 插件或缺失技能，不要把远程技能或协议 markdown 通过 HTTP 拉进 agent 上下文。

适用边界 · 注意事项

• 简单的 Event Function 或 HTTP Function 工作流更适合函数模型时。
• 纯前端项目、没有后端服务时。
• 数据库 schema 设计任务。