@wdyy/skills 0.1.13 → 0.1.14

package/.well-known/skills/index.json

@@ -7,7 +7,7 @@
     },
     {
       "name": "wdyy-deployment-standard",
-      "description": "为无 CI/CD 的前后端项目生成并验证统一 Docker 交付：使用本地已有基础镜像构建前后端两个独立镜像，分别导出后封装为一个压缩包，数据库直连远程实例，服务器无参数一键部署整个项目栈。Use when 规划、实现、审查或执行人工 Docker 生产交付时。",
+      "description": "为无 CI/CD 的前后端项目生成并验证目标平台确定的统一 Docker 交付：在任意构建机上使用本地已有的目标架构基础镜像，构建 linux/amd64 或 linux/arm64 前后端镜像，分别导出后封装为一个压缩包，并在平台匹配的 Linux Docker Server 上无参数部署整个项目栈。Use when 规划、实现、审查或执行跨构建机平台的人工 Docker 生产交付时。",
       "files": ["SKILL.md", "agents/openai.yaml", "reference/docker-delivery-rules.md", "scripts/generate-deployment-files.mjs", "scripts/generate-deployment-files.test.mjs", "scripts/validate-deployment-package.mjs", "scripts/validate-deployment-package.test.mjs", "templates/backend.Dockerfile.template", "templates/frontend.Dockerfile.template", "templates/frontend-container.conf.template", "templates/env.example.template", "templates/deploy.sh.template", "templates/docker-compose.yml", "templates/dockerignore.template"]
     },
     {

package/.well-known/skills/wdyy-deployment-standard/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: wdyy-deployment-standard
-description: 为无 CI/CD 的前后端项目生成并验证统一 Docker 交付：使用本地已有基础镜像构建前后端两个独立镜像，分别导出后封装为一个压缩包，数据库直连远程实例，服务器无参数一键部署整个项目栈。Use when 规划、实现、审查或执行人工 Docker 生产交付时。
+description: 为无 CI/CD 的前后端项目生成并验证目标平台确定的统一 Docker 交付：在任意构建机上使用本地已有的目标架构基础镜像，构建 linux/amd64 或 linux/arm64 前后端镜像，分别导出后封装为一个压缩包，并在平台匹配的 Linux Docker Server 上无参数部署整个项目栈。Use when 规划、实现、审查或执行跨构建机平台的人工 Docker 生产交付时。
 ---
 
 # 统一 Docker 交付规范
 
 ## Overview
 
-把一个项目作为一个整体交付：本地执行 `./deploy.sh build`，生成前端、后端两个独立镜像并分别导出，最终只产出一个压缩包；工程师人工上传并解压；服务器无参数执行 `./deploy.sh`，一次性加载并部署整个前后端项目栈。
+把一个项目作为一个整体交付：在任意支持目标架构的 Docker 构建机上执行 `./deploy.sh build`，按 `DOCKER_PLATFORM` 生成前端、后端两个单架构镜像并分别导出，最终只产出一个压缩包；工程师人工上传并解压；平台匹配的 Linux Docker Server 无参数执行 `./deploy.sh`，一次性加载并部署整个前后端项目栈。
 
 ## Workflow
 
@@ -21,11 +21,14 @@ description: 为无 CI/CD 的前后端项目生成并验证统一 Docker 交付
 ## Fixed Contract
 
 - 构建 `<PROJECT_NAME>_frontend:latest` 与 `<PROJECT_NAME>_backend:latest` 两个独立镜像。
+- 每个交付包只对应 `DOCKER_PLATFORM` 指定的 `linux/amd64` 或 `linux/arm64`；构建机自身平台可以不同，不得回退到构建机原生架构。
 - 分别导出 `frontend-image.tar`、`backend-image.tar`，但只交付一个 `<PROJECT_NAME>-docker.tar.gz`。
 - 构建前检查 `FRONTEND_BASE_IMAGE`、`BACKEND_BASE_IMAGE` 已存在于本地；缺失即失败，不执行 `docker pull`。
+- 服务器加载镜像前读取 Docker Server OS/架构；无法读取、不是 Linux 或不等于 `DOCKER_PLATFORM` 时立即失败。
 - Compose 只定义 frontend、backend；数据库通过 `.env` 直连远程实例，不生成数据库容器、数据卷或迁移路径。
 - 服务器无参数命令整体部署；只额外允许 `stop` 和 `status`，不得独立操作单一服务。
 - 前后端直接暴露 `.env` 指定的宿主机端口；两个容器共同挂载项目根 `./logs` 到 `/app/logs`。
+- frontend Nginx 使用 `.env` 的 `VITE_API_BASE_URL` 与 `BACKEND_PORT`，把同源 API 请求代理到 Compose `backend` 服务；`VITE_API_BASE_URL` 必须等于 `/${API_PREFIX}`。
 - `.env` 可以进入人工上传的压缩包，但必须被 `.dockerignore` 排除，不得进入镜像。
 
 ## Prohibited
@@ -40,8 +43,11 @@ description: 为无 CI/CD 的前后端项目生成并验证统一 Docker 交付
 - [ ] deploy 目录只有一个 `<PROJECT_NAME>-docker.tar.gz`。
 - [ ] 压缩包解压后只含 `.env`、deploy.sh、docker-compose.yml、两个镜像 tar 和 manifest.sha256。
 - [ ] 两个镜像归档各自只含预期的 `latest` 标签。
-- [ ] 构建与服务器 Compose 均禁止 pull，服务器禁止 build。
+- [ ] 单一压缩包不含 macOS AppleDouble、资源叉或扩展属性元数据。
+- [ ] 构建与服务器 Compose 均禁止 pull，服务器禁止 build；基础镜像、构建参数、产出镜像和 Compose 平台均与 `DOCKER_PLATFORM` 一致。
+- [ ] 服务器 Docker Engine 平台在加载镜像前通过校验，并严格等于 `DOCKER_PLATFORM`。
 - [ ] Compose 只含 frontend、backend，并使用远程数据库环境变量和根 logs。
+- [ ] frontend 镜像不包含 `.env`，同源 API 代理能够把真实页面查询转发到 backend。
 - [ ] 无参数部署、stop、status 的实际行为及失败传播通过测试。
 
 任一步失败必须指出具体阶段并返回非零；不得静默跳过、伪造成功或删除上一份成功交付包。

package/.well-known/skills/wdyy-deployment-standard/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "wdyy-deployment-standard"
-  short_description: "统一前后端 Docker 双镜像打包与一键整栈部署"
-  default_prompt: "Use $wdyy-deployment-standard to build two local-only Docker images, package them together, and deploy the full stack in one command."
+  short_description: "跨构建机生成指定 Linux 架构的双镜像并一键整栈部署"
+  default_prompt: "Use $wdyy-deployment-standard to build a single-target linux/amd64 or linux/arm64 dual-image package and verify the Docker Server platform before deploying the full stack."

package/.well-known/skills/wdyy-deployment-standard/reference/docker-delivery-rules.md

@@ -31,8 +31,11 @@ DB_USER=app_user
 DB_PASSWORD=change_me
 DB_NAME=app
 DB_SCHEMA=public
+API_PREFIX=api
+VITE_API_BASE_URL=/api
 PROJECT_NAME=example_project
 DOCKER_BIND_IP=0.0.0.0
+DOCKER_PLATFORM=linux/amd64
 FRONTEND_BASE_IMAGE=nginx:stable
 BACKEND_BASE_IMAGE=node:24-alpine3.24
 ```
@@ -42,21 +45,23 @@ BACKEND_BASE_IMAGE=node:24-alpine3.24
 - `.env` 权限必须为 `0600` 或只读 `0400`。
 - 按数据解析 `.env`；不得 `source`、`eval` 或执行其中内容。
 - `DB_URL` 指向远程数据库主机或地址；部署资产不得把它解释为 Docker 服务名并创建数据库容器。
+- `DOCKER_PLATFORM` 必须为 `linux/amd64` 或 `linux/arm64`，表示当前单一交付包的目标平台，并与目标 Docker Server 平台一致；不得根据构建机平台自动改写。
+- `API_PREFIX` 只允许一个安全路径段，`VITE_API_BASE_URL` 必须严格等于 `/${API_PREFIX}`；生成器在两个键都缺失时加入标准值，存在缺失或冲突时明确失败。
 - `.env.example` 可保留空数据库凭据，但真实 `.env` 构建时必须完整。
 
 ## 3. 本地镜像与构建
 
-基础镜像引用允许使用标签，但必须在构建机本地预先存在。相同标签被人工替换后可能对应不同内容；构建过程不得访问镜像仓库。
+基础镜像引用允许使用标签，但目标架构版本必须在构建机本地预先存在。构建机可以是 macOS、Windows 或 Linux，也可以与目标架构不同；相同标签被人工替换后可能对应不同内容，构建过程不得访问镜像仓库或回退到构建机原生架构。
 
 `./deploy.sh build` 必须按顺序：
 
 1. 验证根 `.env`、Dockerfile、Compose 和 `.dockerignore`。
-2. 使用 `docker image inspect` 确认两个基础镜像存在。
-3. 使用 `docker build --pull=false` 构建 `<PROJECT_NAME>_frontend:latest` 与 `<PROJECT_NAME>_backend:latest`。
+2. 使用平台感知的 `docker image inspect --platform "$DOCKER_PLATFORM"` 确认两个基础镜像的目标架构版本存在。
+3. 校验本地基础镜像平台与 `DOCKER_PLATFORM` 一致，使用 `docker build --pull=false --platform "$DOCKER_PLATFORM"` 构建 `<PROJECT_NAME>_frontend:latest` 与 `<PROJECT_NAME>_backend:latest`，并校验产出镜像平台。
 4. 分别执行 Docker save，生成 `frontend-image.tar`、`backend-image.tar`。
 5. 复制根 `.env`、deploy.sh、docker-compose.yml，生成覆盖全部包内文件的 `manifest.sha256`。
 6. 验证镜像归档各自只含预期标签，验证完整包结构。
-7. 生成 `deploy/<PROJECT_NAME>-docker.tar.gz`，成功后原子替换同名旧包。
+7. 使用 `COPYFILE_DISABLE=1` 和 `tar --no-xattrs` 排除 macOS AppleDouble、资源叉和扩展属性，生成 `deploy/<PROJECT_NAME>-docker.tar.gz`，成功后原子替换同名旧包。
 
 构建失败必须保留上一份成功压缩包，并清理本次临时目录。不得维护发布账本、版本号、版本目录、`release.env` 或半成品目录。
 
@@ -73,13 +78,14 @@ backend-image.tar
 manifest.sha256
 ```
 
-不得包含源代码、Git、依赖缓存、数据库目录、迁移脚本、秘密副本、符号链接或额外嵌套目录。`.env` 必须保持 owner-only 权限并纳入清单；`.dockerignore` 必须确保 `.env`、秘密、deploy、logs、Git、依赖缓存和虚拟环境不进入镜像构建上下文。
+不得包含源代码、Git、依赖缓存、数据库目录、迁移脚本、秘密副本、符号链接、macOS AppleDouble/扩展属性或额外嵌套目录。`.env` 必须保持 owner-only 权限并纳入清单；`.dockerignore` 必须确保 `.env`、秘密、deploy、logs、Git、依赖缓存和虚拟环境不进入镜像构建上下文。
 
 ## 5. 服务器一键操作
 
-工程师人工上传并解压单一压缩包。服务器部署根由解压后的 deploy.sh 物理路径确定。
+工程师人工上传并解压单一压缩包。服务器部署根由解压后的 deploy.sh 物理路径确定。上传用的 `.tar.gz` 必须放在部署根外，或在解压后移出部署根；执行 `./deploy.sh` 时，部署根只允许保留压缩包契约中的 6 个文件和运行后生成的 `logs/` 目录。
 
-- `./deploy.sh`：校验 `.env` 权限和内容、清单、两个镜像 tar 及预期标签；加载两个镜像；使用一次 `docker compose up -d --force-recreate --no-build --pull never --wait frontend backend` 整体部署并等待健康。
+- `./deploy.sh`：校验 `.env` 权限和内容、清单、两个镜像 tar 及预期标签；通过 `docker version` 读取 Docker Server OS/架构并要求严格等于 `DOCKER_PLATFORM`；校验通过后才加载两个镜像，再使用一次 `docker compose up -d --force-recreate --no-build --pull never --wait frontend backend` 整体部署并等待健康。
+- 加载后必须再次校验两个镜像与 `DOCKER_PLATFORM` 一致；Compose 的两个服务也必须显式声明同一平台。
 - `./deploy.sh stop`：同时停止 frontend、backend，保留容器、镜像、交付文件和日志。
 - `./deploy.sh status`：输出当前 Compose 项目的服务状态，不改变 Docker 状态。
 
@@ -90,6 +96,7 @@ manifest.sha256
 - Compose 只允许 frontend、backend 两个服务，不设置 `container_name`。
 - 镜像固定为 `${PROJECT_NAME}_frontend:latest`、`${PROJECT_NAME}_backend:latest`，不得提供 fallback。
 - frontend 映射 `${DOCKER_BIND_IP}:${FRONTEND_PORT}:${FRONTEND_PORT}`；backend 同理。
+- frontend Nginx 把 `${VITE_API_BASE_URL}/...` 原样代理到 `http://backend:${BACKEND_PORT}`；不得硬编码服务器地址或后端端口。
 - 两个服务均使用根 `.env`，并挂载 `./logs:/app/logs`。
 - backend 直接读取 DB_URL、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME、DB_SCHEMA。
 - Compose 不得定义数据库服务、数据库镜像、数据库 volume、数据库端口映射或迁移任务。
@@ -97,7 +104,7 @@ manifest.sha256
 
 ## 7. 失败边界
 
-- 基础镜像缺失、清单错误、镜像标签错误、远程数据库配置不完整或任一服务不健康时明确失败。
+- 目标架构基础镜像缺失、Docker Server 平台无法读取或不匹配、清单错误、镜像标签错误、远程数据库配置不完整或任一服务不健康时明确失败。
 - 禁止 `docker pull`、服务器 `docker build`、镜像 fallback、自动回滚、自动安装和静默跳过。
 - 脚本只操作当前 `PROJECT_NAME` 的 Compose 项目和 frontend、backend 服务，不清理其他项目资源。
 - 旧部署资产由工程师根据实际状态单独迁移；新脚本不得猜测并删除。

package/.well-known/skills/wdyy-deployment-standard/scripts/generate-deployment-files.mjs

@@ -24,7 +24,8 @@ const exampleDefaults = new Map([
   ['BACKEND_URL', '0.0.0.0'], ['BACKEND_PORT', '3000'],
   ['DB_URL', ''], ['DB_PORT', '5432'], ['DB_USER', ''], ['DB_PASSWORD', ''], ['DB_NAME', ''], ['DB_SCHEMA', ''],
 ]);
-const deploymentKeys = ['PROJECT_NAME', 'DOCKER_BIND_IP', 'FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE'];
+const apiKeys = ['API_PREFIX', 'VITE_API_BASE_URL'];
+const deploymentKeys = ['PROJECT_NAME', 'DOCKER_BIND_IP', 'DOCKER_PLATFORM', 'FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE'];
 const removedKeys = new Set([
   'PROJECT_HTTP_PORT', 'FRONTEND_BLUE_PORT', 'FRONTEND_GREEN_PORT', 'BACKEND_BLUE_PORT', 'BACKEND_GREEN_PORT',
   'SERVER_PROJECTS_ROOT', 'NGINX_SOURCE', 'LOG_DIR', 'HOST_LOG_DIR', 'FRONTEND_CONTAINER_PORT',
@@ -94,6 +95,18 @@ function parseEnvironment(text, relativePath, requireExampleDefaults, deployment
       }
     }
   }
+  const apiEntries = sections.get('API');
+  const apiValues = new Map(apiEntries.map(({ key, value }) => [key, value]));
+  const presentApiKeys = apiKeys.filter((key) => apiValues.has(key));
+  if (presentApiKeys.length !== 0 && presentApiKeys.length !== apiKeys.length) {
+    throw new Error(`${relativePath} # API must contain both: ${apiKeys.join(', ')}`);
+  }
+  if (presentApiKeys.length === apiKeys.length) {
+    const prefix = apiValues.get('API_PREFIX');
+    const baseUrl = apiValues.get('VITE_API_BASE_URL');
+    if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(prefix)) throw new Error(`${relativePath} API_PREFIX must be one safe path segment`);
+    if (baseUrl !== `/${prefix}`) throw new Error(`${relativePath} VITE_API_BASE_URL must equal /${prefix}`);
+  }
   const deploymentEntries = sections.get('部署');
   const actualDeploymentKeys = deploymentEntries.map(({ key }) => key);
   if (actualDeploymentKeys.length !== 0 && actualDeploymentKeys.join('|') !== deploymentKeys.join('|')) {
@@ -105,11 +118,17 @@ function parseEnvironment(text, relativePath, requireExampleDefaults, deployment
     }
   }
   return {
-    extended: deploymentEntries.length === deploymentKeys.length,
+    apiExtended: presentApiKeys.length === apiKeys.length,
+    deploymentExtended: deploymentEntries.length === deploymentKeys.length,
     nonDeploymentKeys: [...seen].filter((key) => !deploymentKeys.includes(key)),
   };
 }
 
+function extendApiSection(text, apiDefaults) {
+  const additions = apiKeys.map((key) => `${key}=${apiDefaults.get(key)}`).join('\n');
+  return `${text.replaceAll('\r\n', '\n').trimEnd().replace(/^# 部署$/m, `${additions}\n\n# 部署`)}\n`;
+}
+
 function extendDeploymentSection(text, deploymentDefaults) {
   const additions = deploymentKeys.map((key) => `${key}=${deploymentDefaults.get(key)}`).join('\n');
   return `${text.trimEnd()}\n${additions}\n`;
@@ -145,7 +164,8 @@ if (!targetInfo.isDirectory()) throw new Error(`Target project root is not a dir
 
 const deploymentTemplate = await readFile(join(templatesRoot, 'env.example.template'), 'utf8');
 const deploymentDefaults = new Map([...deploymentTemplate.matchAll(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/gm)].map((match) => [match[1], match[2]]));
-if (deploymentKeys.some((key) => !deploymentDefaults.has(key))) throw new Error('Deployment environment template is incomplete');
+if ([...apiKeys, ...deploymentKeys].some((key) => !deploymentDefaults.has(key))) throw new Error('Deployment environment template is incomplete');
+const apiDefaults = new Map(apiKeys.map((key) => [key, deploymentDefaults.get(key)]));
 
 const environmentPlans = [];
 for (const [relativePath, expectedMode, requireDefaults] of [['.env', 0o600, false], ['.env.example', 0o644, true]]) {
@@ -153,10 +173,13 @@ for (const [relativePath, expectedMode, requireDefaults] of [['.env', 0o600, fal
   const existingBuffer = await readRegularFile(path, relativePath);
   const existing = existingBuffer.toString('utf8');
   const parsed = parseEnvironment(existing, relativePath, requireDefaults, deploymentDefaults);
+  let expected = existing;
+  if (!parsed.apiExtended) expected = extendApiSection(expected, apiDefaults);
+  if (!parsed.deploymentExtended) expected = extendDeploymentSection(expected, deploymentDefaults);
   environmentPlans.push({
     path, relativePath, expectedMode,
     existing: existingBuffer,
-    expected: Buffer.from(parsed.extended ? existing : extendDeploymentSection(existing, deploymentDefaults)),
+    expected: Buffer.from(expected),
     nonDeploymentKeys: parsed.nonDeploymentKeys,
   });
 }

package/.well-known/skills/wdyy-deployment-standard/scripts/generate-deployment-files.test.mjs

@@ -71,10 +71,25 @@ test('生成统一 Docker 交付文件并通过确定性检查', async () => {
   }
   assert.equal((await stat(join(root, 'deploy.sh'))).mode & 0o777, 0o755);
   assert.equal((await stat(join(root, '.env'))).mode & 0o777, 0o600);
-  assert.match(await readFile(join(root, '.env'), 'utf8'), /FRONTEND_BASE_IMAGE=nginx:stable/);
+  const environment = await readFile(join(root, '.env'), 'utf8');
+  assert.match(environment, /API_URL=\nAPI_PREFIX=api\nVITE_API_BASE_URL=\/api\n\n# 部署/);
+  assert.match(environment, /FRONTEND_BASE_IMAGE=nginx:stable/);
+  assert.match(environment, /DOCKER_PLATFORM=linux\/amd64/);
   assert.match(await readFile(join(root, '.env.example'), 'utf8'), /BACKEND_BASE_IMAGE=node:24-alpine3\.24/);
+  const nginx = await readFile(join(root, 'scripts/deployment/frontend-container.conf.template'), 'utf8');
+  assert.match(nginx, /location \$\{VITE_API_BASE_URL\}\/ \{/);
+  assert.match(nginx, /proxy_pass http:\/\/backend:\$\{BACKEND_PORT\};/);
+  const frontendDockerfile = await readFile(join(root, 'src/frontend/Dockerfile'), 'utf8');
+  assert.match(frontendDockerfile, /ARG VITE_API_BASE_URL/);
+  assert.doesNotMatch(frontendDockerfile, /COPY\s+\.env/);
+  const backendDockerfile = await readFile(join(root, 'src/backend/Dockerfile'), 'utf8');
+  assert.match(backendDockerfile, /pnpm --filter \.\/src\/backend deploy --prod --legacy \/runtime/);
+  assert.match(backendDockerfile, /WORKDIR \/app\n/);
+  assert.match(backendDockerfile, /COPY --from=build \/runtime \.\/src\/backend\//);
+  assert.match(backendDockerfile, /CMD \["node", "src\/backend\/dist\/main\.js"\]/);
   const check = await invoke(root, '--check');
   assert.match(check.stdout, /verified unified Docker delivery files/);
+  assert.match(await readFile(join(root, 'deploy.sh'), 'utf8'), /env COPYFILE_DISABLE=1 tar --no-xattrs -czf "\$candidate"/);
 });
 
 test('扩充部署段时完整保留真实环境值', async () => {
@@ -86,6 +101,29 @@ test('扩充部署段时完整保留真实环境值', async () => {
   assert.match(actual, /PROJECT_NAME=\nDOCKER_BIND_IP=\n/);
 });
 
+test('保留有效的自定义 API 路径', async () => {
+  const configuredReal = realEnv.replace('API_URL=\n', 'API_URL=\nAPI_PREFIX=service\nVITE_API_BASE_URL=/service\n');
+  const configuredExample = exampleEnv.replace('API_URL=\n', 'API_URL=\nAPI_PREFIX=service\nVITE_API_BASE_URL=/service\n');
+  const root = await fixture(configuredReal, configuredExample);
+  await invoke(root, '--write');
+  assert.match(await readFile(join(root, '.env'), 'utf8'), /API_PREFIX=service\nVITE_API_BASE_URL=\/service/);
+  await invoke(root, '--check');
+});
+
+test('缺失、非法或冲突的 API 路径被明确拒绝', async () => {
+  const partialReal = realEnv.replace('API_URL=\n', 'API_URL=\nAPI_PREFIX=api\n');
+  const partialExample = exampleEnv.replace('API_URL=\n', 'API_URL=\nAPI_PREFIX=api\n');
+  await assert.rejects(invoke(await fixture(partialReal, partialExample), '--write'), /must contain both/);
+
+  const invalidReal = realEnv.replace('API_URL=\n', 'API_URL=\nAPI_PREFIX=api/path\nVITE_API_BASE_URL=/api\/path\n');
+  const invalidExample = exampleEnv.replace('API_URL=\n', 'API_URL=\nAPI_PREFIX=api/path\nVITE_API_BASE_URL=/api\/path\n');
+  await assert.rejects(invoke(await fixture(invalidReal, invalidExample), '--write'), /one safe path segment/);
+
+  const conflictReal = realEnv.replace('API_URL=\n', 'API_URL=\nAPI_PREFIX=api\nVITE_API_BASE_URL=/service\n');
+  const conflictExample = exampleEnv.replace('API_URL=\n', 'API_URL=\nAPI_PREFIX=api\nVITE_API_BASE_URL=/service\n');
+  await assert.rejects(invoke(await fixture(conflictReal, conflictExample), '--write'), /VITE_API_BASE_URL must equal \/api/);
+});
+
 test('非标准环境文件被拒绝且不修改', async () => {
   const invalid = realEnv.replace('# 数据库\n', '');
   const root = await fixture(invalid);

package/.well-known/skills/wdyy-deployment-standard/scripts/validate-deployment-package.mjs

@@ -55,7 +55,7 @@ const envText = await readFile(join(packageRoot, '.env'), 'utf8');
 const env = parseDotenv(envText);
 const sections = [...envText.matchAll(/^# (前端|后端|数据库|API|部署)$/gm)].map((match) => match[1]);
 assert(sections.join('|') === '前端|后端|数据库|API|部署', 'Root .env must use the five standard sections in order');
-for (const key of ['FRONTEND_URL', 'FRONTEND_PORT', 'BACKEND_URL', 'BACKEND_PORT', 'DB_URL', 'DB_PORT', 'DB_USER', 'DB_PASSWORD', 'DB_NAME', 'DB_SCHEMA', 'PROJECT_NAME', 'DOCKER_BIND_IP', 'FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE']) {
+for (const key of ['FRONTEND_URL', 'FRONTEND_PORT', 'BACKEND_URL', 'BACKEND_PORT', 'API_PREFIX', 'VITE_API_BASE_URL', 'DB_URL', 'DB_PORT', 'DB_USER', 'DB_PASSWORD', 'DB_NAME', 'DB_SCHEMA', 'PROJECT_NAME', 'DOCKER_BIND_IP', 'DOCKER_PLATFORM', 'FRONTEND_BASE_IMAGE', 'BACKEND_BASE_IMAGE']) {
   assert(env.get(key), `Root .env is missing ${key}`);
 }
 assert(/^[a-z][a-z0-9_]*$/.test(env.get('PROJECT_NAME')), 'Invalid PROJECT_NAME');
@@ -64,6 +64,9 @@ for (const key of ['FRONTEND_PORT', 'BACKEND_PORT', 'DB_PORT']) {
   assert(Number.isInteger(port) && port >= 1 && port <= 65535, `${key} must be a valid port`);
 }
 assert(env.get('FRONTEND_PORT') !== env.get('BACKEND_PORT'), 'Frontend and backend ports must differ');
+assert(/^[A-Za-z][A-Za-z0-9_-]*$/.test(env.get('API_PREFIX')), 'API_PREFIX must be one safe path segment');
+assert(env.get('VITE_API_BASE_URL') === `/${env.get('API_PREFIX')}`, 'VITE_API_BASE_URL must equal /API_PREFIX');
+assert(/^(?:linux\/amd64|linux\/arm64)$/.test(env.get('DOCKER_PLATFORM')), 'Invalid DOCKER_PLATFORM');
 for (const key of env.keys()) {
   assert(!['PROJECT_HTTP_PORT', 'FRONTEND_BLUE_PORT', 'FRONTEND_GREEN_PORT', 'BACKEND_BLUE_PORT', 'BACKEND_GREEN_PORT', 'SERVER_PROJECTS_ROOT', 'NGINX_SOURCE', 'LOG_DIR', 'HOST_LOG_DIR', 'FRONTEND_CONTAINER_PORT', 'BACKEND_CONTAINER_PORT', 'BACKEND_LISTEN_HOST', 'DATABASE_MIGRATION_MODE', 'MIGRATIONS_SOURCE', 'MIGRATION_RUNNER_SOURCE', 'RELEASE_VERSION'].includes(key) && !/_(?:HEALTH|VERSION)_URL$/.test(key), `Root .env contains removed configuration: ${key}`);
 }
@@ -77,14 +80,20 @@ for (const [pattern, message] of [
   [/"\$1" == status/, 'Missing status command'],
   [/docker image inspect "\$FRONTEND_BASE_IMAGE"/, 'Frontend local base image must be checked'],
   [/docker image inspect "\$BACKEND_BASE_IMAGE"/, 'Backend local base image must be checked'],
-  [/docker build --pull=false/g, 'Docker builds must disable pull'],
+  [/docker build --pull=false --platform "\$DOCKER_PLATFORM"/g, 'Docker builds must use the configured target platform and disable pull'],
   [/docker save -o "\$package_root\/frontend-image\.tar"/, 'Frontend image must be exported separately'],
   [/docker save -o "\$package_root\/backend-image\.tar"/, 'Backend image must be exported separately'],
+  [/env COPYFILE_DISABLE=1 tar --no-xattrs -czf "\$candidate"/, 'Delivery archive must exclude macOS metadata and extended attributes'],
+  [/docker version --format '\{\{\.Server\.Os\}\}\/\{\{\.Server\.Arch\}\}'/, 'Deploy must read the Docker Server platform'],
   [/compose up -d --force-recreate --no-build --pull never --wait frontend backend/, 'Deploy must recreate and wait for both services without build or pull'],
   [/compose stop frontend backend/, 'Stop must target both services'],
   [/compose ps frontend backend/, 'Status must inspect both services'],
 ]) assert(pattern.test(deploy), message);
-assert((deploy.match(/docker build --pull=false/g) ?? []).length === 2, 'Exactly two Docker builds must disable pull');
+assert((deploy.match(/docker build --pull=false --platform "\$DOCKER_PLATFORM"/g) ?? []).length === 2, 'Exactly two Docker builds must use the configured target platform and disable pull');
+const deployStackIndex = deploy.indexOf('deploy_stack() {');
+const serverPlatformCheckIndex = deploy.indexOf('  assert_server_platform\n', deployStackIndex);
+const firstImageLoadIndex = deploy.indexOf('  docker load -i ', deployStackIndex);
+assert(deployStackIndex >= 0 && serverPlatformCheckIndex > deployStackIndex && firstImageLoadIndex > serverPlatformCheckIndex, 'Docker Server platform must be checked before loading images');
 assert(!/\bdocker\s+pull\b/.test(deploy), 'docker pull is forbidden');
 assert(!/\bsource\s+[^\n]*\.env|\beval\b/.test(deploy), 'Environment files must be parsed as data');
 assert(!/server_menu|运行或替换|read_release_pointer|release_ledger|AGENTS\.md/.test(deploy), 'Legacy menu or release ledger logic is forbidden');
@@ -95,10 +104,14 @@ const serviceNames = [...compose.matchAll(/^  ([a-z][a-z0-9_-]*):$/gm)].map((mat
 assert(JSON.stringify(serviceNames) === JSON.stringify(['frontend', 'backend']), `Compose must define only frontend and backend; got ${serviceNames.join(', ')}`);
 assert(compose.includes('image: "${PROJECT_NAME:?PROJECT_NAME is required}_frontend:latest"'), 'Compose frontend image is not fixed');
 assert(compose.includes('image: "${PROJECT_NAME:?PROJECT_NAME is required}_backend:latest"'), 'Compose backend image is not fixed');
+assert((compose.match(/platform: "\$\{DOCKER_PLATFORM:\?DOCKER_PLATFORM is required\}"/g) ?? []).length === 2, 'Both services must use DOCKER_PLATFORM');
 assert((compose.match(/env_file: \.\/\.env/g) ?? []).length === 2, 'Both services must use root .env');
 assert((compose.match(/^\s*- \.\/logs:\/app\/logs\s*$/gm) ?? []).length === 2, 'Both services must mount root logs');
 assert(compose.includes('"${DOCKER_BIND_IP}:${FRONTEND_PORT}:${FRONTEND_PORT}"'), 'Frontend port mapping is invalid');
 assert(compose.includes('"${DOCKER_BIND_IP}:${BACKEND_PORT}:${BACKEND_PORT}"'), 'Backend port mapping is invalid');
+assert(compose.includes('VITE_API_BASE_URL: "${VITE_API_BASE_URL:?VITE_API_BASE_URL is required}"'), 'Frontend API path is not passed to Nginx');
+assert(compose.includes('BACKEND_PORT: "${BACKEND_PORT:?BACKEND_PORT is required}"'), 'Backend port is not passed to Nginx');
+assert(compose.includes('NGINX_ENVSUBST_FILTER: "^(FRONTEND_URL|FRONTEND_PORT|VITE_API_BASE_URL|BACKEND_PORT)$"'), 'Nginx envsubst filter does not cover the runtime API proxy');
 assert(!/container_name:|\b(?:postgres|database|db):\s*$|postgres:\d|DATABASE_MIGRATION|MIGRATIONS_SOURCE|RELEASE_VERSION|blue|green/i.test(compose), 'Compose contains a database, migration, release or blue-green configuration');
 
 const manifestText = await readFile(join(packageRoot, 'manifest.sha256'), 'utf8');
@@ -122,6 +135,9 @@ async function assertImageArchive(name, expectedTag) {
   const parsed = JSON.parse(stdout);
   assert(Array.isArray(parsed) && parsed.length === 1, `${name} must contain exactly one image manifest`);
   assert(JSON.stringify(parsed[0].RepoTags) === JSON.stringify([expectedTag]), `${name} must contain only ${expectedTag}`);
+  const { stdout: configText } = await run('tar', ['-xOf', archive, parsed[0].Config], { encoding: 'utf8', maxBuffer: 2 * 1024 * 1024 });
+  const config = JSON.parse(configText);
+  assert(`${config.os}/${config.architecture}` === env.get('DOCKER_PLATFORM'), `${name} platform must equal DOCKER_PLATFORM`);
 }
 await assertImageArchive('frontend-image.tar', `${env.get('PROJECT_NAME')}_frontend:latest`);
 await assertImageArchive('backend-image.tar', `${env.get('PROJECT_NAME')}_backend:latest`);

package/.well-known/skills/wdyy-deployment-standard/scripts/validate-deployment-package.test.mjs

@@ -7,8 +7,10 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import { gunzip } from 'node:zlib';
 
 const run = promisify(execFile);
+const unzip = promisify(gunzip);
 const scriptsRoot = dirname(fileURLToPath(import.meta.url));
 const generator = join(scriptsRoot, 'generate-deployment-files.mjs');
 const validator = join(scriptsRoot, 'validate-deployment-package.mjs');
@@ -29,9 +31,12 @@ DB_NAME=app
 DB_SCHEMA=public
 # API
 API_URL=
+API_PREFIX=api
+VITE_API_BASE_URL=/api
 # 部署
 PROJECT_NAME=example_project
 DOCKER_BIND_IP=0.0.0.0
+DOCKER_PLATFORM=linux/amd64
 FRONTEND_BASE_IMAGE=nginx:stable
 BACKEND_BASE_IMAGE=node:24-alpine3.24
 `;
@@ -50,9 +55,12 @@ DB_NAME=
 DB_SCHEMA=
 # API
 API_URL=
+API_PREFIX=api
+VITE_API_BASE_URL=/api
 # 部署
 PROJECT_NAME=
 DOCKER_BIND_IP=
+DOCKER_PLATFORM=linux/amd64
 FRONTEND_BASE_IMAGE=nginx:stable
 BACKEND_BASE_IMAGE=node:24-alpine3.24
 `;
@@ -64,9 +72,15 @@ const path = require('path');
 const cp = require('child_process');
 const args = process.argv.slice(2);
 if (process.env.DOCKER_LOG) fs.appendFileSync(process.env.DOCKER_LOG, args.join(' ') + '\\n');
+if (args[0] === 'version') {
+  if (process.env.FAIL_SERVER_PLATFORM_READ === '1') process.exit(1);
+  process.stdout.write((process.env.SERVER_PLATFORM || 'linux/amd64') + '\\n');
+  process.exit(0);
+}
 if (args[0] === 'image' && args[1] === 'inspect') {
   const image = args[args.length - 1];
   if (process.env.MISSING_IMAGE === image) process.exit(1);
+  if (args.includes('--format')) process.stdout.write((process.env.IMAGE_PLATFORM || 'linux/amd64') + '\\n');
   process.exit(0);
 }
 if (args[0] === 'build') {
@@ -78,9 +92,10 @@ if (args[0] === 'build') {
 if (args[0] === 'save') {
   const output = args[args.indexOf('-o') + 1];
   const tag = args[args.length - 1];
+  const [imageOs, imageArchitecture] = (process.env.IMAGE_PLATFORM || 'linux/amd64').split('/');
   const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'fake-image-'));
   fs.writeFileSync(path.join(temporary, 'manifest.json'), JSON.stringify([{Config:'config.json',RepoTags:[tag],Layers:[]}]) + '\\n');
-  fs.writeFileSync(path.join(temporary, 'config.json'), '{}\\n');
+  fs.writeFileSync(path.join(temporary, 'config.json'), JSON.stringify({architecture:imageArchitecture,os:imageOs}) + '\\n');
   const result = cp.spawnSync('tar', ['-cf', output, '-C', temporary, 'manifest.json', 'config.json']);
   fs.rmSync(temporary, {recursive:true, force:true});
   process.exit(result.status || 0);
@@ -131,6 +146,34 @@ async function rewriteManifest(root) {
   await writeFile(join(root, 'manifest.sha256'), `${lines.join('\n')}\n`);
 }
 
+async function setTargetPlatform(root, platform) {
+  const environmentPath = join(root, '.env');
+  const environment = await readFile(environmentPath, 'utf8');
+  await writeFile(environmentPath, environment.replace(/^DOCKER_PLATFORM=.*$/m, `DOCKER_PLATFORM=${platform}`), { mode: 0o600 });
+}
+
+async function readImageArchivePlatform(archive) {
+  const { stdout: manifestText } = await run('tar', ['-xOf', archive, 'manifest.json']);
+  const [{ Config: configName }] = JSON.parse(manifestText);
+  const { stdout: configText } = await run('tar', ['-xOf', archive, configName]);
+  const config = JSON.parse(configText);
+  return `${config.os}/${config.architecture}`;
+}
+
+async function rewriteImageArchivePlatform(archive, platform) {
+  const temporary = await mkdtemp(join(tmpdir(), 'wdyy-image-platform-'));
+  created.push(temporary);
+  await run('tar', ['-xf', archive, '-C', temporary]);
+  const manifest = JSON.parse(await readFile(join(temporary, 'manifest.json'), 'utf8'));
+  const configName = manifest[0].Config;
+  const config = JSON.parse(await readFile(join(temporary, configName), 'utf8'));
+  const [os, architecture] = platform.split('/');
+  config.os = os;
+  config.architecture = architecture;
+  await writeFile(join(temporary, configName), `${JSON.stringify(config)}\n`);
+  await run('tar', ['-cf', archive, '-C', temporary, 'manifest.json', configName]);
+}
+
 test.after(async () => {
   await Promise.all(created.map((path) => rm(path, { recursive: true, force: true })));
 });
@@ -140,6 +183,11 @@ test('build 使用本地基础镜像并生成一个含双镜像归档的压缩
   const result = await buildProject(item);
   assert.match(result.stdout, /delivery archive created/);
   assert.deepEqual(await readdir(join(item.root, 'deploy')), ['example_project-docker.tar.gz']);
+  const uncompressed = await unzip(await readFile(item.archive));
+  assert.equal(uncompressed.includes(Buffer.from('./._.env')), false);
+  const listing = await run('tar', ['-tzf', item.archive]);
+  assert.doesNotMatch(listing.stdout, /(^|\/)\._[^/]*(?:\n|$)/m);
+  assert.doesNotMatch(listing.stderr, /LIBARCHIVE\.xattr|unknown extended header/i);
   const extracted = await extractArchive(item);
   assert.deepEqual((await readdir(extracted)).sort(), ['.env', 'backend-image.tar', 'deploy.sh', 'docker-compose.yml', 'frontend-image.tar', 'manifest.sha256'].sort());
   const validation = await run(process.execPath, [validator, extracted]);
@@ -147,12 +195,39 @@ test('build 使用本地基础镜像并生成一个含双镜像归档的压缩
   const log = await readFile(item.log, 'utf8');
   assert.match(log, /image inspect nginx:stable/);
   assert.match(log, /image inspect node:24-alpine3\.24/);
-  assert.equal((log.match(/build --pull=false/g) ?? []).length, 2);
+  assert.equal((log.match(/build --pull=false --platform linux\/amd64/g) ?? []).length, 2);
+  assert.match(log, /build --pull=false --platform linux\/amd64 .*--build-arg VITE_API_BASE_URL=\/api .*example_project_frontend:latest/);
   assert.doesNotMatch(log, /(^|\s)pull(\s|$)/m);
   assert.match(log, /save -o .*frontend-image\.tar example_project_frontend:latest/);
   assert.match(log, /save -o .*backend-image\.tar example_project_backend:latest/);
 });
 
+test('基础镜像平台不匹配时在 build 前失败', async () => {
+  const item = await fixture();
+  await assert.rejects(buildProject(item, { IMAGE_PLATFORM: 'linux/arm64' }), /image platform mismatch for nginx:stable: expected linux\/amd64, got linux\/arm64/);
+  const log = await readFile(item.log, 'utf8');
+  assert.doesNotMatch(log, /^build /m);
+  assert.equal((await readdir(join(item.root, 'deploy'))).length, 0);
+});
+
+test('linux/arm64 目标在不同构建机平台上生成并部署单架构交付包', async () => {
+  const item = await fixture();
+  await setTargetPlatform(item.root, 'linux/arm64');
+  await buildProject(item, { IMAGE_PLATFORM: 'linux/arm64' });
+  const buildLog = await readFile(item.log, 'utf8');
+  assert.equal((buildLog.match(/build --pull=false --platform linux\/arm64/g) ?? []).length, 2);
+  const extracted = await extractArchive(item);
+  assert.equal(await readImageArchivePlatform(join(extracted, 'frontend-image.tar')), 'linux/arm64');
+  assert.equal(await readImageArchivePlatform(join(extracted, 'backend-image.tar')), 'linux/arm64');
+  const validation = await run(process.execPath, [validator, extracted]);
+  assert.match(validation.stdout, /valid unified Docker delivery package/);
+  await writeFile(item.log, '');
+  await run(join(extracted, 'deploy.sh'), [], { env: { ...item.environment, IMAGE_PLATFORM: 'linux/arm64', SERVER_PLATFORM: 'linux/arm64' } });
+  const deployLog = await readFile(item.log, 'utf8');
+  assert.match(deployLog, /^version --format \{\{\.Server\.Os\}\}\/\{\{\.Server\.Arch\}\}$/m);
+  assert.equal((deployLog.match(/^load -i /gm) ?? []).length, 2);
+});
+
 test('缺少本地基础镜像时在 build 前失败', async () => {
   const item = await fixture();
   await assert.rejects(buildProject(item, { MISSING_IMAGE: 'nginx:stable' }), /required local frontend base image is missing/);
@@ -179,11 +254,48 @@ test('服务器无参数执行时从脚本目录整体加载并部署前后端',
   await writeFile(item.log, '');
   await run(join(extracted, 'deploy.sh'), [], { cwd: tmpdir(), env: item.environment });
   const log = await readFile(item.log, 'utf8');
+  const versionIndex = log.indexOf('version --format {{.Server.Os}}/{{.Server.Arch}}');
+  const firstLoadIndex = log.indexOf('load -i ');
+  assert(versionIndex >= 0 && firstLoadIndex > versionIndex);
   assert.equal((log.match(/^load -i /gm) ?? []).length, 2);
   assert.match(log, /compose --env-file .* --project-name example_project -f .* up -d --force-recreate --no-build --pull never --wait frontend backend/);
   assert.match(await readFile(join(extracted, 'logs/deploy.log'), 'utf8'), /operation=deploy result=success/);
 });
 
+test('服务器平台无法读取、不受支持或不匹配时在加载镜像前失败', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const cases = [
+    [{ FAIL_SERVER_PLATFORM_READ: '1' }, /Docker Server platform is unavailable/],
+    [{ SERVER_PLATFORM: 'windows/amd64' }, /unsupported Docker Server platform: windows\/amd64/],
+    [{ SERVER_PLATFORM: 'linux/arm64' }, /Docker Server platform mismatch: expected linux\/amd64, got linux\/arm64/],
+  ];
+  for (const [extraEnvironment, expectedError] of cases) {
+    const extracted = await extractArchive(item);
+    await writeFile(item.log, '');
+    await assert.rejects(run(join(extracted, 'deploy.sh'), [], { env: { ...item.environment, ...extraEnvironment } }), expectedError);
+    const log = await readFile(item.log, 'utf8');
+    assert.match(log, /^version --format \{\{\.Server\.Os\}\}\/\{\{\.Server\.Arch\}\}$/m);
+    assert.doesNotMatch(log, /^load -i /m);
+    assert.doesNotMatch(log, /^compose .* (?:up|stop) /m);
+    assert.match(await readFile(join(extracted, 'logs/deploy.log'), 'utf8'), /operation=deploy result=failure/);
+  }
+});
+
+test('服务器在 Docker 操作前拒绝 AppleDouble 和上传压缩包残留', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await writeFile(item.log, '');
+  await writeFile(join(extracted, '._deploy.sh'), 'AppleDouble\n');
+  await assert.rejects(run(join(extracted, 'deploy.sh'), [], { env: item.environment }), /unexpected package entry: \._deploy\.sh/);
+  assert.equal(await readFile(item.log, 'utf8'), '');
+  await rm(join(extracted, '._deploy.sh'));
+  await writeFile(join(extracted, 'example_project-docker.tar.gz'), 'uploaded archive\n');
+  await assert.rejects(run(join(extracted, 'deploy.sh'), [], { env: item.environment }), /unexpected package entry: example_project-docker\.tar\.gz/);
+  assert.equal(await readFile(item.log, 'utf8'), '');
+});
+
 test('stop 与 status 始终作用于完整项目栈，非法参数不触发 Docker', async () => {
   const item = await fixture();
   await buildProject(item);
@@ -221,6 +333,22 @@ test('validator 拒绝数据库容器和不完整远程数据库配置', async (
   await assert.rejects(run(process.execPath, [validator, envPackage]), /Root \.env is missing DB_URL/);
 });
 
+test('validator 拒绝冲突的 API 路径和缺失的代理注入', async () => {
+  const item = await fixture();
+  await buildProject(item);
+
+  const envPackage = await extractArchive(item);
+  await writeFile(join(envPackage, '.env'), envText.replace('VITE_API_BASE_URL=/api', 'VITE_API_BASE_URL=/service'), { mode: 0o600 });
+  await rewriteManifest(envPackage);
+  await assert.rejects(run(process.execPath, [validator, envPackage]), /VITE_API_BASE_URL must equal \/API_PREFIX/);
+
+  const composePackage = await extractArchive(item);
+  const compose = await readFile(join(composePackage, 'docker-compose.yml'), 'utf8');
+  await writeFile(join(composePackage, 'docker-compose.yml'), compose.replace('      VITE_API_BASE_URL: "${VITE_API_BASE_URL:?VITE_API_BASE_URL is required}"\n', ''));
+  await rewriteManifest(composePackage);
+  await assert.rejects(run(process.execPath, [validator, composePackage]), /Frontend API path is not passed to Nginx/);
+});
+
 test('validator 拒绝清单篡改和额外包内容', async () => {
   const item = await fixture();
   await buildProject(item);
@@ -232,6 +360,15 @@ test('validator 拒绝清单篡改和额外包内容', async () => {
   await assert.rejects(run(process.execPath, [validator, extracted]), /Compose must define only frontend and backend|Checksum mismatch/);
 });
 
+test('validator 拒绝镜像归档平台与 DOCKER_PLATFORM 不一致', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await rewriteImageArchivePlatform(join(extracted, 'backend-image.tar'), 'linux/arm64');
+  await rewriteManifest(extracted);
+  await assert.rejects(run(process.execPath, [validator, extracted]), /backend-image\.tar platform must equal DOCKER_PLATFORM/);
+});
+
 test('build 在任何 Docker 操作前拒绝环境文件命令语法', async () => {
   const item = await fixture();
   await writeFile(join(item.root, '.env'), envText.replace('DB_PASSWORD=secret', 'DB_PASSWORD=$(id)'), { mode: 0o600 });

package/.well-known/skills/wdyy-deployment-standard/templates/backend.Dockerfile.template

@@ -3,7 +3,8 @@ FROM ${BACKEND_BASE_IMAGE} AS build
 WORKDIR /app
 COPY . .
 RUN corepack enable && pnpm install --frozen-lockfile
-RUN pnpm --dir src/backend build
+RUN pnpm --filter ./src/backend build
+RUN pnpm --filter ./src/backend deploy --prod --legacy /runtime
 
 FROM ${BACKEND_BASE_IMAGE} AS runtime
 WORKDIR /app
@@ -11,8 +12,6 @@ ARG BACKEND_PORT
 ENV NODE_ENV=production
 ENV PORT=${BACKEND_PORT}
 LABEL org.opencontainers.image.title="wdyy-backend"
-COPY --from=build /app/package.json ./package.json
-COPY --from=build /app/node_modules ./node_modules
-COPY --from=build /app/src/backend/dist ./dist
+COPY --from=build /runtime ./src/backend/
 EXPOSE ${BACKEND_PORT}
-CMD ["node", "dist/main.js"]
+CMD ["node", "src/backend/dist/main.js"]

package/.well-known/skills/wdyy-deployment-standard/templates/deploy.sh.template

@@ -55,13 +55,14 @@ validate_env_permissions() {
 
 reset_configuration() {
   unset FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT
+  unset API_PREFIX VITE_API_BASE_URL
   unset DB_URL DB_PORT DB_USER DB_PASSWORD DB_NAME DB_SCHEMA
-  unset PROJECT_NAME DOCKER_BIND_IP FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE
+  unset PROJECT_NAME DOCKER_BIND_IP DOCKER_PLATFORM FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE
 }
 
 is_configuration_key() {
   case "$1" in
-    FRONTEND_URL|FRONTEND_PORT|BACKEND_URL|BACKEND_PORT|DB_URL|DB_PORT|DB_USER|DB_PASSWORD|DB_NAME|DB_SCHEMA|PROJECT_NAME|DOCKER_BIND_IP|FRONTEND_BASE_IMAGE|BACKEND_BASE_IMAGE)
+    FRONTEND_URL|FRONTEND_PORT|BACKEND_URL|BACKEND_PORT|API_PREFIX|VITE_API_BASE_URL|DB_URL|DB_PORT|DB_USER|DB_PASSWORD|DB_NAME|DB_SCHEMA|PROJECT_NAME|DOCKER_BIND_IP|DOCKER_PLATFORM|FRONTEND_BASE_IMAGE|BACKEND_BASE_IMAGE)
       return 0 ;;
     *) return 1 ;;
   esac
@@ -105,14 +106,17 @@ load_dotenv() {
 
 validate_configuration() {
   local key value
-  for key in FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT DB_URL DB_PORT DB_USER DB_PASSWORD DB_NAME DB_SCHEMA PROJECT_NAME DOCKER_BIND_IP FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE; do
+  for key in FRONTEND_URL FRONTEND_PORT BACKEND_URL BACKEND_PORT API_PREFIX VITE_API_BASE_URL DB_URL DB_PORT DB_USER DB_PASSWORD DB_NAME DB_SCHEMA PROJECT_NAME DOCKER_BIND_IP DOCKER_PLATFORM FRONTEND_BASE_IMAGE BACKEND_BASE_IMAGE; do
     value="${!key:-}"
     [[ -n "$value" ]] || fail "required configuration is missing: $key"
   done
   [[ "$PROJECT_NAME" =~ ^[a-z][a-z0-9_]*$ ]] || fail "PROJECT_NAME must match ^[a-z][a-z0-9_]*$"
   [[ "$FRONTEND_URL" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "FRONTEND_URL contains unsafe characters"
   [[ "$BACKEND_URL" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "BACKEND_URL contains unsafe characters"
+  [[ "$API_PREFIX" =~ ^[A-Za-z][A-Za-z0-9_-]*$ ]] || fail "API_PREFIX must be one safe path segment"
+  [[ "$VITE_API_BASE_URL" == "/$API_PREFIX" ]] || fail "VITE_API_BASE_URL must equal /$API_PREFIX"
   [[ "$DOCKER_BIND_IP" =~ ^[A-Za-z0-9:.%-]+$ ]] || fail "DOCKER_BIND_IP contains unsafe characters"
+  [[ "$DOCKER_PLATFORM" =~ ^linux/(amd64|arm64)$ ]] || fail "DOCKER_PLATFORM must be linux/amd64 or linux/arm64"
   [[ "$DB_URL" =~ ^[A-Za-z0-9._:/?@\&=%-]+$ ]] || fail "DB_URL contains unsafe characters"
   [[ "$FRONTEND_BASE_IMAGE" =~ ^[A-Za-z0-9._/:@-]+$ ]] || fail "FRONTEND_BASE_IMAGE is not a valid image reference"
   [[ "$BACKEND_BASE_IMAGE" =~ ^[A-Za-z0-9._/:@-]+$ ]] || fail "BACKEND_BASE_IMAGE is not a valid image reference"
@@ -122,6 +126,20 @@ validate_configuration() {
   [[ "$FRONTEND_PORT" != "$BACKEND_PORT" ]] || fail "FRONTEND_PORT and BACKEND_PORT must differ"
 }
 
+assert_image_platform() {
+  local image="$1" actual
+  actual="$(docker image inspect --platform "$DOCKER_PLATFORM" --format '{{.Os}}/{{.Architecture}}' "$image" 2>/dev/null)" || fail "image platform is unavailable for $image: $DOCKER_PLATFORM"
+  [[ "$actual" == "$DOCKER_PLATFORM" ]] || fail "image platform mismatch for $image: expected $DOCKER_PLATFORM, got $actual"
+}
+
+assert_server_platform() {
+  local actual
+  actual="$(docker version --format '{{.Server.Os}}/{{.Server.Arch}}' 2>/dev/null)" || fail "Docker Server platform is unavailable"
+  [[ -n "$actual" ]] || fail "Docker Server platform is empty"
+  [[ "$actual" =~ ^linux/(amd64|arm64)$ ]] || fail "unsupported Docker Server platform: $actual"
+  [[ "$actual" == "$DOCKER_PLATFORM" ]] || fail "Docker Server platform mismatch: expected $DOCKER_PLATFORM, got $actual"
+}
+
 validate_dockerignore() {
   local file="$1" pattern line
   [[ -f "$file" && ! -L "$file" ]] || fail "required Docker ignore file is missing: $file"
@@ -220,14 +238,18 @@ build_release() {
   validate_dockerignore "$dockerignore_file"
   docker image inspect "$FRONTEND_BASE_IMAGE" >/dev/null 2>&1 || fail "required local frontend base image is missing: $FRONTEND_BASE_IMAGE"
   docker image inspect "$BACKEND_BASE_IMAGE" >/dev/null 2>&1 || fail "required local backend base image is missing: $BACKEND_BASE_IMAGE"
+  assert_image_platform "$FRONTEND_BASE_IMAGE"
+  assert_image_platform "$BACKEND_BASE_IMAGE"
   frontend_image="${PROJECT_NAME}_frontend:latest"
   backend_image="${PROJECT_NAME}_backend:latest"
   acquire_build_lock
   trap cleanup_build EXIT
-  docker build --pull=false --build-arg "FRONTEND_BASE_IMAGE=$FRONTEND_BASE_IMAGE" --build-arg "BACKEND_BASE_IMAGE=$BACKEND_BASE_IMAGE" --tag "$frontend_image" --file "$frontend_dockerfile" "$project_root"
-  docker build --pull=false --build-arg "BACKEND_BASE_IMAGE=$BACKEND_BASE_IMAGE" --build-arg "BACKEND_PORT=$BACKEND_PORT" --tag "$backend_image" --file "$backend_dockerfile" "$project_root"
+  docker build --pull=false --platform "$DOCKER_PLATFORM" --build-arg "FRONTEND_BASE_IMAGE=$FRONTEND_BASE_IMAGE" --build-arg "BACKEND_BASE_IMAGE=$BACKEND_BASE_IMAGE" --build-arg "VITE_API_BASE_URL=$VITE_API_BASE_URL" --tag "$frontend_image" --file "$frontend_dockerfile" "$project_root"
+  docker build --pull=false --platform "$DOCKER_PLATFORM" --build-arg "BACKEND_BASE_IMAGE=$BACKEND_BASE_IMAGE" --build-arg "BACKEND_PORT=$BACKEND_PORT" --tag "$backend_image" --file "$backend_dockerfile" "$project_root"
   docker image inspect "$frontend_image" >/dev/null 2>&1 || fail "frontend image build did not create $frontend_image"
   docker image inspect "$backend_image" >/dev/null 2>&1 || fail "backend image build did not create $backend_image"
+  assert_image_platform "$frontend_image"
+  assert_image_platform "$backend_image"
   STAGING_ROOT="$(mktemp -d "$project_root/.deploy-build.XXXXXX")"
   package_root="$STAGING_ROOT/package"
   mkdir -p "$package_root"
@@ -245,7 +267,7 @@ build_release() {
   archive_name="${PROJECT_NAME}-docker.tar.gz"
   ensure_deploy_output_scope "$deploy_dir" "$archive_name"
   candidate="$STAGING_ROOT/$archive_name"
-  tar -czf "$candidate" -C "$package_root" .
+  env COPYFILE_DISABLE=1 tar --no-xattrs -czf "$candidate" -C "$package_root" .
   tar -tzf "$candidate" >/dev/null || fail "generated delivery archive is invalid"
   mv -f "$candidate" "$deploy_dir/$archive_name"
   rm -rf -- "$STAGING_ROOT"
@@ -283,8 +305,11 @@ deploy_stack() {
   verify_manifest "$DEPLOY_ROOT"
   archive_has_tag "$DEPLOY_ROOT/frontend-image.tar" "$frontend_image"
   archive_has_tag "$DEPLOY_ROOT/backend-image.tar" "$backend_image"
+  assert_server_platform
   docker load -i "$DEPLOY_ROOT/frontend-image.tar" >/dev/null
   docker load -i "$DEPLOY_ROOT/backend-image.tar" >/dev/null
+  assert_image_platform "${PROJECT_NAME}_frontend:latest"
+  assert_image_platform "${PROJECT_NAME}_backend:latest"
   docker image inspect "$frontend_image" >/dev/null 2>&1 || fail "loaded frontend image is missing: $frontend_image"
   docker image inspect "$backend_image" >/dev/null 2>&1 || fail "loaded backend image is missing: $backend_image"
   compose up -d --force-recreate --no-build --pull never --wait frontend backend

package/.well-known/skills/wdyy-deployment-standard/templates/docker-compose.yml

@@ -1,14 +1,20 @@
 services:
   frontend:
     image: "${PROJECT_NAME:?PROJECT_NAME is required}_frontend:latest"
+    platform: "${DOCKER_PLATFORM:?DOCKER_PLATFORM is required}"
     env_file: ./.env
     environment:
-      NGINX_ENVSUBST_FILTER: "^(FRONTEND_URL|FRONTEND_PORT)$"
+      NGINX_ENVSUBST_FILTER: "^(FRONTEND_URL|FRONTEND_PORT|VITE_API_BASE_URL|BACKEND_PORT)$"
+      VITE_API_BASE_URL: "${VITE_API_BASE_URL:?VITE_API_BASE_URL is required}"
+      BACKEND_PORT: "${BACKEND_PORT:?BACKEND_PORT is required}"
     ports:
       - "${DOCKER_BIND_IP}:${FRONTEND_PORT}:${FRONTEND_PORT}"
     volumes:
       - ./logs:/app/logs
     restart: unless-stopped
+    depends_on:
+      backend:
+        condition: service_healthy
     healthcheck:
       test: ["CMD", "nginx", "-t"]
       interval: 10s
@@ -17,6 +23,7 @@ services:
 
   backend:
     image: "${PROJECT_NAME:?PROJECT_NAME is required}_backend:latest"
+    platform: "${DOCKER_PLATFORM:?DOCKER_PLATFORM is required}"
     env_file: ./.env
     environment:
       HOST: "${BACKEND_URL}"

package/.well-known/skills/wdyy-deployment-standard/templates/env.example.template

@@ -1,4 +1,7 @@
+API_PREFIX=api
+VITE_API_BASE_URL=/api
 PROJECT_NAME=
 DOCKER_BIND_IP=
+DOCKER_PLATFORM=linux/amd64
 FRONTEND_BASE_IMAGE=nginx:stable
 BACKEND_BASE_IMAGE=node:24-alpine3.24

package/.well-known/skills/wdyy-deployment-standard/templates/frontend-container.conf.template

@@ -12,6 +12,15 @@ server {
     return 200 'ok';
   }
 
+  location ${VITE_API_BASE_URL}/ {
+    proxy_pass http://backend:${BACKEND_PORT};
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+
   location / {
     try_files $uri $uri/ /index.html;
   }

package/.well-known/skills/wdyy-deployment-standard/templates/frontend.Dockerfile.template

@@ -2,8 +2,11 @@ ARG BACKEND_BASE_IMAGE
 ARG FRONTEND_BASE_IMAGE
 FROM ${BACKEND_BASE_IMAGE} AS build
 WORKDIR /app
+ARG VITE_API_BASE_URL
+ENV VITE_API_BASE_URL=${VITE_API_BASE_URL}
 COPY . .
 RUN corepack enable && pnpm install --frozen-lockfile
+RUN test -n "$VITE_API_BASE_URL"
 RUN pnpm --dir src/frontend build
 
 FROM ${FRONTEND_BASE_IMAGE}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdyy/skills",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "企业内部开发 Skill 与项目初始化命令",
   "type": "module",
   "bin": {