From 321d2e616535cc55aad78d3acec547b42130c1d4 Mon Sep 17 00:00:00 2001 From: Lon Date: Sat, 1 Aug 2026 02:59:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20scope=20A=20=E2=80=94=20=E5=A6=99?= =?UTF-8?q?=E6=90=AD=20experimental,=20ordinary=20Dockerfile=20main=20path?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align skill with company-deploy-mcp: support matrix, no gateway/login parity promise, boot-only self-host env note. --- dokploy-gitea-deploy/SKILL.md | 26 ++++++-- .../references/stack-profiles.md | 61 ++++++++++++------- 2 files changed, 62 insertions(+), 25 deletions(-) diff --git a/dokploy-gitea-deploy/SKILL.md b/dokploy-gitea-deploy/SKILL.md index 5d44cf3..10fb2ce 100644 --- a/dokploy-gitea-deploy/SKILL.md +++ b/dokploy-gitea-deploy/SKILL.md @@ -32,13 +32,16 @@ Skill 只提供流程；真正部署还需配置 MCP `company-deploy`（`buxi_` **默认路径：company-deploy-mcp（必须优先）。** 直连 Dokploy API 为 **legacy / 运维例外**。 +**产品范围（收口）：** 主路径是 **普通 Dockerfile 服务**（Python / Node / 静态站等）。 +飞书 **妙搭 / `@lark-apaas/*` 模板不是主路径**——不承诺登录、权限、平台 API 与线上一致；控制面仅可能注入 **进程启动** 所需最小 env。详见 `references/stack-profiles.md` 支持矩阵。 + 参考： - `references/mcp-deploy.md` — **MCP 默认状态机**（工具参数、域名/卷/库） - `references/domain.md` — 域名与 HTTPS（Let’s Encrypt，无需通配符证书） - `references/sequence.md` — 时序 - `references/env-deploy.example` — 仅 legacy 直连用 -- `references/stack-profiles.md` — Dockerfile 约定 +- `references/stack-profiles.md` — Dockerfile 约定 + **支持矩阵** 线上连接中心：`https://company-deploy-mcp.loncode.site/` MCP endpoint：`https://company-deploy-mcp.loncode.site/mcp` @@ -123,6 +126,11 @@ MCP endpoint：`https://company-deploy-mcp.loncode.site/mcp` - 识别栈；保证 Dockerfile；`.gitignore` 排除密钥 - 有状态：默认 `/data`；多目录用 `persistence[]` - 需要库：`databases: [{ engine: "postgres"|"mysql", ... }]` +- **若依赖 `@lark-apaas/*` / 妙搭模板：** + - **先告知用户**：本平台不保证页面+接口可用；推荐 `lark-apps` 云端或业务去平台化 + - **禁止**主动承诺「自托管后与妙搭一致」 + - **禁止**在 skill 流程里大改登录/伪造网关/补 SPA 模板（那是业务仓责任，且非本 skill 范围） + - 用户书面坚持后，仅按普通 Dockerfile 部署，交付时标注 **实验性** - **Node 多阶段硬规则**（详见 `stack-profiles.md`）： - 禁止在 `npm ci`/`pnpm install` **之前** `ENV NODE_ENV=production`（否则 `nest`/`vite` not found） - 大前端 Vite：`NODE_OPTIONS=--max-old-space-size=3072` @@ -227,12 +235,14 @@ Agent **不要**在 MCP 路径下再调 Dokploy `domain.create`（避免双绑/ | 用户说法 | 动作 | |----------|------| -| 部署 / 上线 / 第一次发布 | MCP 全链路；交付 `url` | +| 部署 / 上线 / 第一次发布 | MCP 全链路；交付 `url`（普通 Dockerfile） | | 重试 / 再构建 | 新 SHA → 新 plan → apply（已有 mapping） | | 查状态 / 我的项目 | `list_projects` / `get_deployment_status` | | 配额 | `get_my_quota` | | 只要链接 | `list_projects` 看 `url`；无则查 status | | 运维直连 Dokploy | 仅明确要求时走 legacy | +| 妙搭应用 / `@lark-apaas` 上线 | **先边界说明**；优先 `lark-apps`；自托管仅实验、不承诺接口 | +| 修妙搭白屏 / 平台 API / 登录伪造 | **非本 skill**；说明需业务去平台化或妙搭云端，勿在控制面堆适配 | --- @@ -243,12 +253,18 @@ Agent **不要**在 MCP 路径下再调 Dokploy `domain.create`（避免双绑/ - 已发布当前版本 - 访问：`https://buxi….loncode.site/`（以 MCP 返回为准） - 需要库时：说明已注入数据库连接（**不打印密码**） +- 若为妙搭实验部署：明确 **「仅容器/入口可能可用，登录与平台接口不保证」** **失败：** - 配额满 / 未登录 Key / 构建失败 / 证书签发中 - 给可执行下一步，不暴露平台密钥 +**拒绝加戏：** + +- 不要为了「页面像妙搭」去改 skill 流程、伪造网关、承诺 runtime API +- 控制面 `SELF_HOST_*` 只是 boot 兜底，不是功能完整度保证 + --- ## 安全红线 @@ -292,7 +308,8 @@ Agent **不要**在 MCP 路径下再调 Dokploy `domain.create`（避免双绑/ | 场景 | 用 | |------|-----| | 企业 Dockerfile 部署（默认） | **本 skill → MCP** | -| 妙搭云端发布 | `lark-apps` | +| 妙搭云端发布 / 平台能力迭代 | **`lark-apps`**（首选） | +| 妙搭模板硬上自托管 | 非主路径；见 `stack-profiles`；**不**在本 skill 做深度适配 | | 无 MCP 的运维救火 | 本 skill → legacy | --- @@ -305,7 +322,8 @@ Agent **不要**在 MCP 路径下再调 Dokploy `domain.create`（避免双绑/ | git push 权限 / Permission denied / 要配 SSH | **错误路径**。改用 `ensure_repository` → `agentHint.pushUrl` 推送；禁止给用户配 SSH | | `nest: not found` / `vite: not found` | build 阶段在装依赖前设了 `NODE_ENV=production`；先全量 `npm ci` 再设 production | | `JavaScript heap out of memory` | Dockerfile build 加 `NODE_OPTIONS=--max-old-space-size=3072`；避免并行 npm ci；机器内存过小则升配 | -| `FORCE_AUTHN_INNERAPI_DOMAIN` / 平台模式需要基础域名 | 妙搭模板自部署缺 env；控制面 apply 会注入；老应用再 apply 或 Dokploy 手动补公网 URL | +| `FORCE_AUTHN_INNERAPI_DOMAIN` / 平台模式需要基础域名 | 镜像仍带 PlatformModule 时缺 boot env；`apply` 会注入公网 URL；**不表示业务已可用** | +| 妙搭项目：页面白屏 / `{{appId}}` / 接口 403·404 / JSON 解析 HTML | **预期内能力缺口**（非本 skill 必修）。引导去平台化或 `lark-apps`；勿在控制面加网关适配 | | 运行中项目达上限 | `get_my_quota`；停/删旧应用后再部署 | | Forbidden 看他人项目 | 非管理员；加 `ADMIN_OPEN_IDS` 或只查自己的 | | 有部署无 HTTPS | 等 LE；查 DNS/80；控制面证书配置 | diff --git a/dokploy-gitea-deploy/references/stack-profiles.md b/dokploy-gitea-deploy/references/stack-profiles.md index a61a15e..f36a016 100644 --- a/dokploy-gitea-deploy/references/stack-profiles.md +++ b/dokploy-gitea-deploy/references/stack-profiles.md @@ -9,37 +9,49 @@ 5. 健康检查：实现 `/healthz` 或约定路径，写入 `spec.healthcheckPath`。 6. Dokploy **不要每次 cleanCache**。 7. **有状态数据写挂载路径**（见下），不要只写容器可写层。 -8. **本控制面 = 自部署（self-host）**，不是飞书妙搭/TCE 平台托管。 +8. **本控制面 = 普通容器自部署**（Gitea + Dokploy），**不是**飞书妙搭 / TCE 托管平台。 -### 飞书 APaaS / 妙搭模板（`@lark-apaas/*`）自部署 +--- -模板里的 `PlatformModule.forRoot()` 会启用平台 HttpClient（`platform.enabled: true`），启动时**必须**有： +## 支持矩阵（Agent 选型） + +| 栈 | 状态 | Agent 默认行为 | +|----|------|----------------| +| 普通 Python / Node / 静态站 + Dockerfile | **支持** | 正常 create → apply → 交付 URL | +| 自管 Nest/FastAPI/Flask（自己的登录与 DB） | **支持** | 同上 | +| 飞书妙搭 / `@lark-apaas/*` 全栈模板 | **实验性 · 非主路径** | **不要承诺「可用」**；先告知用户边界；仅用户坚持且理解风险时才部署 | +| 依赖妙搭网关登录 / `/spark` runtime / 平台对象存储 / 插件能力 | **不支持** | 引导 `lark-apps` 在妙搭发布，或业务侧去平台化后再上本控制面 | + +**主路径产品承诺：** 有 Dockerfile、监听约定端口、状态写 `/data`、可选 PG/MySQL → HTTPS 链接。 +**不承诺：** 与妙搭线上一致的登录、权限、平台 API、观测、能力插件。 + +### 妙搭 / Lark APaaS（仅 boot 兜底，非适配层） + +若镜像里仍带着 `PlatformModule`（`platform.enabled: true`），**进程启动**可能需要： ```text -FORCE_AUTHN_INNERAPI_DOMAIN=<基础域名> +FORCE_AUTHN_INNERAPI_DOMAIN=<应用公网 URL> ``` -否则： +控制面 `apply` **仅注入最小 boot env**（可关：`SELF_HOST_INJECT_ENV=false`），**不做**登录伪造、SPA 模板渲染、runtime API 补齐： -```text -Error: 平台模式需要基础域名，请设置环境变量 FORCE_AUTHN_INNERAPI_DOMAIN -``` - -**控制面在 `apply` 时自动注入**（无需用户填妙搭平台域名）： - -| 变量 | 值 | -|------|-----| -| `FORCE_AUTHN_INNERAPI_DOMAIN` | 应用公网 URL（`https://buxi*****.DOMAIN_ROOT`） | -| `FORCE_FRAMEWORK_DISABLE_DATAPASS` | `true`（关掉 TCE datapass 中间件） | -| `FORCE_FRAMEWORK_ENVIRONMENT` | 默认 `development` | +| 变量 | 作用 | +|------|------| +| `FORCE_AUTHN_INNERAPI_DOMAIN` | 公网 URL，避免 HttpClient 构造失败 | +| `FORCE_FRAMEWORK_ENVIRONMENT` | 默认 `development`（`SELF_HOST_FRAMEWORK_ENVIRONMENT`） | +| `FORCE_FRAMEWORK_DISABLE_DATAPASS` | 默认 **`false`**（保留 DataPaas → `DRIZZLE_DATABASE`；勿默认关掉） | +| `COMPANY_DEPLOY_SELF_HOST` | 标记自部署，供业务仓可选分支 | | `SERVER_HOST` / `SERVER_PORT` / `PORT` | `0.0.0.0` + `spec.port` | -| `COMPANY_DEPLOY_SELF_HOST` | `true` | +| `SUDA_DATABASE_URL` / `DATABASE_URL` | 仅当 plan 带了 `databases[]` 时写入 | -说明： +**明确不在控制面 / skill 范围：** -- 这只保证 **进程能启动**；飞书开放平台能力（多维表格等）仍需业务侧配置 `FEISHU_*` / 应用凭证。 -- 若应用硬依赖妙搭登录态，自部署还需业务改登录（本地账号 / 自建 OAuth），与控制面注入无关。 -- 已上线的老应用：再 `apply` 一次，或 Dokploy 手动补上表中变量后 Redeploy。 +- 注入 `window.appId` / `__BASENAME__` / CSRF 与 hbs 模板（须业务仓自己处理或去平台化） +- 伪造 `x-larkgw-suda-webuser`、业务 `users` 种子、角色权限 +- `/spark`、`/__runtime__`、观测 collect、平台账号/对象存储 +- 保证页面「能打开且接口正常」 + +Agent 话术：检测到 `@lark-apaas` 时，**先说明「仅可能进程可启动，接口与登录不保证」**；推荐改为普通栈或妙搭云端（`lark-apps`）。用户仍要求部署时，按普通 Dockerfile 流程走，**交付时写明实验性**。 --- @@ -259,3 +271,10 @@ registry=https://registry.npmmirror.com - [ ] 需要 PG/MySQL 时 plan 带 `databases`，代码读对应 env - [ ] Web 服务 `exposeWeb: true`（默认）；Worker 显式 `false` - [ ] `.gitignore` 排除 `.env`、密钥、本地 db + + +### DataPaas / DRIZZLE（仅当镜像仍用 @lark-apaas DataPaas） + +- 保持 `FORCE_FRAMEWORK_DISABLE_DATAPASS=false`（默认） +- plan 带 Postgres 时控制面会写 `SUDA_DATABASE_URL` + `DATABASE_URL` +- 这只服务 **Nest 注入**；不代表业务接口已可用