40 lines
2.6 KiB
Markdown
40 lines
2.6 KiB
Markdown
# Works Square 项目 ZIP 打包契约
|
||
|
||
创建、检查或修复 Works Square 项目 ZIP 时使用本契约。服务端只接受可由 Docker Compose 构建和运行的安全 ZIP 包。
|
||
|
||
## 根目录和必需内容
|
||
|
||
ZIP 根目录直接包含 `niancode.yml`、`docker-compose.yml`、Compose build context 使用的源码、引用的 `Dockerfile*`、构建使用的 lock 文件，以及运行所需静态资源和配置。不能出现 `project/niancode.yml` 这种额外目录套壳。
|
||
|
||
## 大小、计数和路径安全
|
||
|
||
- ZIP 文件大小不得超过 `50 MB`。
|
||
- 解压后总大小不得超过 `200 MB`。
|
||
- 文件数不得超过 `2000`。
|
||
- 禁止绝对路径、盘符路径、`..` 路径穿越、空路径片段、重复规范化路径和符号链接。
|
||
- 每个条目必须能被普通 ZIP 解压器读取。
|
||
|
||
默认排除 `node_modules/`、`.git/`、`build/`、`dist/`、`.next/`、`.nuxt/`、`.vite/`、`.dart_tool/`、`.pub-cache/`、`android/.gradle/`、`ios/Pods/`、`.venv/`、`venv/`、`__pycache__/`、`*.pyc`、`.pytest_cache/`、`.DS_Store`、真实 `.env`、证书、私钥和本地密钥。优先使用白名单，只加入实际构建和运行需要的文件。
|
||
|
||
## niancode.yml
|
||
|
||
根目录 UTF-8 YAML 必须声明 `runtime: compose`、`compose.file: docker-compose.yml`、存在于 Compose 的 `compose.public_service`，以及 `compose.public_port: 8080`。
|
||
|
||
## Docker Compose
|
||
|
||
公开服务的容器内应用监听 `0.0.0.0:8080`，端口只写为 `127.0.0.1::8080`。禁止固定宿主机端口、非 loopback 绑定和仅写 `"8080"`。
|
||
|
||
拒绝 `privileged: true`、`network_mode: host`、`pid: host`、`ipc: host`、`/var/run/docker.sock` 挂载、绝对宿主机路径挂载，以及绝对或包含 `..` 的 build context / Dockerfile 路径。多服务项目只让公开服务发布端口；浏览器所需 `/api/...` 由公开服务反向代理到 Compose 内部后端。
|
||
|
||
## Dockerfile
|
||
|
||
构建必须无交互，不依赖宿主机预装 Node、Python 或 Flutter，不引用本地绝对路径。基础镜像必须可获取；依赖安装尽量使用 lock 文件；语言版本约束必须与基础镜像提供的运行时一致。
|
||
|
||
## 本地验证链
|
||
|
||
依次记录 `docker compose config`、`build --pull=false`、`up -d`、`docker port`、HTTP 冒烟、`down -v`，以及重新打开 ZIP 后的结构、安全、大小和计数检查。Docker 不可用时，把未执行项标记为“未验证”或“失败/阻塞”。
|
||
|
||
## 页面交接
|
||
|
||
项目根目录 `works-publish.json` 供“部署与上传”页面读取，不是服务端 ZIP 校验必填项，也不能替代 ZIP 根目录的 Compose 文件。只有实际提交后才能记录提交成功。
|