Openship 部署配置完全指南openship.json 全字段参考与源码级解析【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openshipopenship.json是 Openship 部署平台自托管 PaaS在仓库根目录的声明式部署配置文件作用类似于 Vercel 的vercel.json或 Railway 的railway.toml它声明项目如何构建、运行、路由与扩容。本文以 .claude/skills/openship-config/references/fields.md 为骨架逐字段讲解类型、取值范围与底层行为并结合仓库源码schema.ts、parse.ts、parse.test.ts与 CLI 实现config.ts做纵深印证。读完本文你将能够熟练编写、校验并调试任意复杂度的openship.json。openship.json 的本质权威覆盖层Authoritative Overlay在深入字段之前必须先理解整个配置文件的运行模型。openship.json不是一份完整清单而是一层覆盖overlayOpenship 会先对仓库做全自动检测框架、包管理器、构建命令、端口等配置文件中存在的字段覆盖检测值缺失的字段保持检测到的值不变。因此一份好的openship.json应该尽量小而精只声明你确定要固定或覆盖的内容而不是把检测结果原样抄一遍。这个设计在 schema.ts 的模块注释中有明确说明Auto-detection runs first, then each field present here overrides it (absent fields keep the detected value). It seeds the wizard and is authoritative for headless deploys (auto-deploy on push,openship deploy). 同时runtime、productionMode、domains、resources等字段还会预填部署向导wizard影响后续交互式部署的默认值。关于校验SKILL.md 与 CLI 实现指出配置文件与部署流水线共用同一个解析器parseOpenshipConfigJson来自repo/core。这意味着openship config validate通过的文件在实际部署时的行为完全一致反之部署时遇到的拒绝信息也与本地校验一致见 config.ts 的注释。这是本地校验即线上行为的关键保证。工作流从零编写并校验配置文件理解仓库查看package.jsonscripts、dependencies、锁文件判定包管理器、框架配置文件next.config.*、vite.config.*、astro.config.*等、是否包含docker-compose.yml以及是否为 monorepopnpm-workspace.yaml、turbo.json、apps/*、packages/*。决定覆盖什么检测已经正确的内容不要写只有当仓库需要非默认行为时才加字段——自定义构建命令、固定端口、自定义域名、密钥、compose 服务、云端资源规格等。编写openship.json放在仓库根目录始终以$schema行开头以获得编辑器自动补全{ $schema: https://openship.io/openship.schema.json }校验执行openship config validate或openship config validate path/to/openship.json修复所有报错。若仓库还没有配置文件可用openship config init生成一个最小可用的起步文件。openship config init在本地做零依赖、无网络的廉价检测见 config.ts 的detectHints按pnpm-lock.yaml、yarn.lock、bun.lockb、package-lock.json的顺序推断包管理器再从package.json的scripts.build/scripts.start推断构建与启动命令。生成文件同样以$schema开头随后只有检测到的字段——其余全部省略交给自动检测。注意openship.json是纯 JSON 而非 JSONC——不允许注释不允许尾逗号。Build 构建字段字段类型说明framework枚举技术栈 slug见下文列表。覆盖自动检测结果。packageManager枚举npmyarnpnpmbungocargopippoetrypipenvuvbundlercomposermavengradledotnetmixrootDirectorystring应用目录相对仓库根例如./、apps/web。composePathstring位于检测到的根目录之外的 compose 文件——可以是文件本身deploy/stack.yml同时覆盖非标准文件名也可以是存放它的文件夹deploy/docker-compose。声明后项目即成为 compose 部署build:上下文按 compose 语义相对该文件夹解析。installCommandstring依赖安装命令。buildCommandstring构建命令。startCommandstring生产启动命令。outputDirectorystring构建输出目录dist、.next、build、out等。buildImagestring构建用 Docker 镜像例如node:22。productionPathsstring[]作为生产产物打包发布的路径列表。framework 可选值nextjsnuxtsveltekitremixastroviteangulargatsbycravuereactexpressfastifyhononestjskoaadoniselysiagoginfiberechorustactixaxumrocketpythondjangoflaskfastapirailssinatralaravelsymfonyspringbootquarkuskotlindotnetblazorphoenixnodestaticdockerdocker-composewebmail。packageManager 与 framework 的底层约束这两个枚举并非随意字符串而是在 stacks.ts 的**栈注册表stack registry**中统一维护的每种语言JavaScript、Go、Rust、Python、Ruby、PHP、Java、C#、Elixir 等各自定义了可用的包管理器集合、默认构建镜像与运行时镜像。例如 JavaScript/TypeScript 使用node:22作为构建与运行时镜像、支持npm/yarn/pnpm/bunGo 使用golang:1.22-alpine构建、运行时为alpine:3.19。解析器parse.ts通过STACK_IDS与ALL_PACKAGE_MANAGERS校验字段值不在列表中的值会被记为硬性错误见 parse.ts因此请严格使用上文列出的 slug。Runtime 运行时字段字段类型说明runtimebare|docker单个应用的运行时隔离方式。services/docker 项目恒为docker。会预填新部署的运行时选择。productionModehost|static|standalonestatic⇒ 以文件方式直接托管相当于hasServerfalse。portinteger 1–65535服务监听端口。volumesstring[]跨部署保留的路径。裸路径 相对应用根目录如storage完整挂载语法uploads:/app/storage、/srv/data:/app/var。省略则继承框架默认Laravel 默认保留storage/[]表示关闭持久化。compose 服务请改用services[].volumes。runtime决定单个应用以裸进程bare还是 Docker 容器方式运行而productionMode决定产物形态——static模式下应用被当作静态文件托管不启动任何服务器进程。值得一提的细节在 schema.ts 中还存在一个较新的workload字段web|worker|static它是运行时轴线的现代表达web监听端口并被路由worker是不对外路由的无端口常驻容器static以文件方式托管。productionMode仍然受支持并被映射到该轴host/standalone → webstatic → static以保证存量配置兼容当两者同时设置时workload优先。volumes的两种形态应用相对路径与完整挂载在 schema.ts 的注释中亦有详细说明。Env 环境变量env是一个对象值为两种形态之一普通字符串PUBLIC_URL: https://app.acme.com对象{ value: string, secret?: boolean }——secret: true标记该变量在静态存储时加密encrypted at rest。env: { PUBLIC_URL: https://app.acme.com, API_KEY: { value: sk_live_…, secret: true } }建议对任何敏感内容数据库连接串、API Key、密码使用逐键的secret: true。解析器对env的校验相当严格值必须是字符串或{ value, secret }对象对象缺少value会直接报错env.A.value is required见 parse.ts。secret字段的类型必须是布尔值。顶层env与 service 级env使用同一套解析逻辑parseEnv因此两种场景的写法完全一致。Domains 域名domains是一个数组每个元素可以是纯主机名字符串myapp对象见下表字段类型说明domainstring主机名。裸标签 免费子域名带点 自定义域名。portinteger该主机名路由到哪个端口。targetPathstring目标端的路径前缀默认/。typefree|custom显式覆盖免费/自定义的自动推断。domains: [ myapp, { domain: api.acme.com, port: 8080, targetPath: /v1, type: custom } ]解析器parseDomains会把纯字符串元素规范化为{ domain: item }对象因此两种写法最终等价测试 parse.test.ts 明确断言了这一规范化行为。domain字段必填缺失会报requires a domain。type仅在自动推断裸标签→free、带点→custom不符合预期时用于显式覆盖。Routes 路由规则routes在部署时编译为反向代理reverse proxy配置实现类 Vercel 的路径级控制字段类型说明rewrites{ source, destination }[]内部重写例如 SPA fallback。redirects{ source, destination, permanent?, statusCode? }[]3xx 重定向。headers{ source, headers: { key, value }[] }[]按路径设置响应头。cleanUrlsboolean去除.html后缀。trailingSlashboolean强制/移除结尾斜杠。routes: { cleanUrls: true, redirects: [{ source: /old, destination: /new, permanent: true }], headers: [ { source: /api/*, headers: [{ key: X-Frame-Options, value: DENY }] } ] }从解析器实现parseRoutes可以看到几个值得注意的约束rewrites/redirects的每条规则都必须同时具备source与destination否则该条被丢弃redirects的statusCode被限制在300–399之间超出即报错permanent: true等价于 308 一类永久重定向语义也可用statusCode精确控制headers条目中key必填、value允许为空字符串。Resources 资源规格resources可以是具名档位tier也可以是显式数值——显式数值会被视为custom档。自托管环境默认unlimited——不设任何上限因为机器本身归操作者所有机器容量就是天花板。只有在想刻意限制某个容器时才需要声明该档位。非零数值会针对目标机器的真实容量做校验因此大型自托管机器可以被充分利用校验上限只是合理性护栏真正上限是目标机器探测到的实际容量在服务端强制见 parse.ts 与测试 parse.test.ts。云端工作区cloud workspaces是按量计费的必须显式指定大小unlimited在云端会被拒绝省略时回退到low。字段类型取值范围tierunlimited|micro|low|medium|highunlimited仅限自托管cpuCoresnumber0 不限制否则 ≥ 0.25上限为目标机器核数memoryMbinteger0 不限制否则 ≥ 128上限为目标机器内存diskMbinteger0 不限制否则 64–204800仅云端工作区补充一个源码层面的细节在 schema.ts 中OpenshipResourceTier类型还额外包含xlargeOPENSHIP_RESOURCE_TIERS常量为unlimited、micro、low、medium、high、xlarge六档解析器也接受该值。此外解析器对显式数值设置了安全护栏cpuCores0–1024、memoryMb0–4194304、diskMb0–204800见 parse.ts——护栏只防笔误不限制大型机器的合理描述。Services 服务compose 多服务services是一个数组声明它即把项目变为多服务Docker项目。两种互斥的用法若要部署已存在的 compose 文件而不是在此重新声明其服务请设置composePath并省略services。字段类型说明namestring必填。imagestring预构建镜像例如postgres:17。buildstring构建上下文路径。dockerfilestringDockerfile 路径。portsstring[]例如[3000]、[5432:5432]。volumesstring[]例如[pgdata:/var/lib/postgresql/data]。dependsOnstring[]依赖的其他服务名。envenv 对象与顶层env同构。commandstring覆盖容器命令。restartno|always|on-failure|unless-stopped重启策略。exposedboolean是否对外路由。exposedPortstring暴露的是哪个容器端口。domainstring该服务的公网主机名。healthcheckobject{ test, interval, timeout, retries, startPeriod, disable }。resourcesobject按字段覆盖顶层resources的每服务上限结构相同0 不限制。services: [ { name: web, build: ., ports: [3000], exposed: true, domain: app.acme.com }, { name: db, image: postgres:17, volumes: [pgdata:/var/lib/postgresql/data], env: { POSTGRES_PASSWORD: { value: …, secret: true } }, restart: unless-stopped } ]解析器对services的强制约束name必填缺失报requires a namerestart必须是四个枚举值之一ports/volumes/dependsOn必须是字符串数组见 parse.ts 与测试 parse.test.ts。compose 文件自身的mem_limit/cpus/deploy.resources.limits会被同等读取并应用无需在此重复声明——这与services[].resources实现了对 compose 资源语法的平权支持schema.ts 注释说明 per-service 资源与 composemem_limit/deploy.resources.limits对等。此外每个 service 还可选声明healthcheckDocker 守护进程循环执行的 HEALTHCHECK与readiness部署流水线一次性是否已就绪探测是唯一能令部署失败的就绪门二者职责不同详见 schema.ts。Monorepo 配置monorepo用于覆盖检测到的子应用sub-app。注意它覆盖的是检测器已经找到的子应用而不是从零声明应用——Openship 的检测器负责发现子应用monorepo.apps[]只负责改写其构建行为。字段类型说明workspace.packageManagerstring根工作区包管理器。workspace.prepareCommandstring在每个子应用构建之前、于仓库根目录运行一次。apps[]array每个子应用的构建覆盖项。每个apps[]条目namerootDirectory必填按rootDirectory路径匹配并覆盖对应检测子应用支持的覆盖项为framework、packageManager、installCommand、buildCommand、startCommand、outputDirectory、buildImage、port。每个子应用的domain/env在向导wizard中设置而不是写在这里——共享变量请放在顶层env/domains见 schema.ts 的OpenshipMonorepoApp定义与注释。monorepo: { workspace: { packageManager: pnpm, prepareCommand: pnpm install }, apps: [ { name: web, rootDirectory: apps/web, framework: nextjs, port: 3000 }, { name: api, rootDirectory: apps/api, framework: hono, port: 8080 } ] }解析器对monorepo的约束parse.tsworkspace必须有packageManagerapps[]每项必须同时具备name与rootDirectory子应用的framework同样受STACK_IDS枚举约束。暂不支持不要添加的字段以下字段虽然会被宽松地校验leniently validated但不会被应用not applied请直接省略sleepMode休眠模式monorepo 的sharedPaths共享路径每个子应用的domain/env/exposed。解析器对未知顶层字段只产生警告warning而非错误字段被忽略parse.tssharedPaths同理产生 is not applied yet (ignored) 警告。openship config validate在存在警告时仍会通过但会提示警告数量。校验机制错误与警告的边界openship config validate的行为由 config.ts 定义其底层调用parseOpenshipConfigJsonparse.ts。校验结果分两类errors硬错误类型错误、未知枚举、超出取值范围如port超出 1–65535、framework不在STACK_IDS中、statusCode不在 300–399、env对象缺value、service 缺name等——任何一条存在都判定为不通过warnings软警告未知顶层键、sharedPaths等——不影响通过但会提示。值得强调的是部署流水线deploy prepare pipeline对配置采用宽松叠加策略忽略errors直接应用可解析部分而openship config validate则严格要求errors为空。自 #641 起部署端也会报告同样的拒绝原因而不是静默应用部分配置。CLI 还保留了引擎的 JSON 语法错误原文便于精确定位你本机文件中的非法字符config.ts。测试用例 parse.test.ts 覆盖了上述全部关键行为完整配置解析并剥离undefined字段、字符串端口自动强转为数字8080→8080、未知 framework 与越界端口报错、大机型资源值合法、0与unlimited合法、每服务资源覆盖、service 必填name、未知顶层键仅警告等——这些测试是理解字段边界的最佳活文档。典型配置三例静态站点SSG 构建产物直接托管{ $schema: https://openship.io/openship.schema.json, framework: vite, buildCommand: pnpm build, outputDirectory: dist, productionMode: static }带自定义域名与密钥的服务端应用{ $schema: https://openship.io/openship.schema.json, framework: nextjs, port: 3000, runtime: docker, env: { NEXT_PUBLIC_URL: https://app.acme.com, DATABASE_URL: { value: postgres://…, secret: true } }, domains: [app.acme.com] }compose 多服务项目声明services即切换为 Docker 运行时{ $schema: https://openship.io/openship.schema.json, services: [ { name: web, build: ., ports: [3000], exposed: true, domain: app.acme.com }, { name: db, image: postgres:17, volumes: [pgdata:/var/lib/postgresql/data], env: { POSTGRES_PASSWORD: { value: …, secret: true } }, restart: unless-stopped } ] }常见坑与最佳实践保持最小化每个字段都会覆盖检测值无用的字段只是噪音。遵循检测正确就不写的原则。JSON 而非 JSONC不允许注释与尾逗号。services与monorepo是单应用配置的替代方案而非叠加项——声明services即表示这是多服务 Docker 项目。monorepo.apps[]是覆盖而非声明子应用由检测器发现条目按rootDirectory匹配后覆盖其构建字段。云端必须显式指定资源云端unlimited会被拒绝省略回退low自托管默认unlimited。敏感变量逐键加secret: true而不是依赖整份配置的加密。本地先校验写完即跑openship config validate因为部署端复用同一解析器通过即代表线上行为一致。延伸阅读官方字段速查.claude/skills/openship-config/references/fields.md编写工作流与通用形态.claude/skills/openship-config/SKILL.md类型定义含workload、readiness等扩展字段schema.ts校验与强转实现parse.ts行为测试字段边界的活文档parse.test.ts技术栈注册表framework / packageManager 枚举来源stacks.tsCLIinit/validate实现config.ts【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考