2.6 KiB
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 文件。只有实际提交后才能记录提交成功。