Openship 自托管部署平台完全指南：内置 CI/CD 的开源 PaaS 中文手册
【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship
Openship 是一个开源、可自托管的部署平台，内置 CI/CD，把「推送代码 → 构建 → 发布 → 域名/TLS 路由 → 邮件/备份」整条链路收敛进一个工具。本文以官方中文 README（docs/i18n/README.zh.md）为骨架，结合仓库源码（CLI 实现、Compose 编排、环境变量参考）逐项展开，读完你将掌握 Openship 的安装方式、运行形态、功能边界、CLI 用法与关键配置参数，能够独立完成从零部署到日常运维。
Openship 控制台界面
项目定位：一个「指向仓库即可发布」的部署平台
Openship 的核心使用方式极其简单：把它指向一个代码仓库，它会自动检测技术栈、构建、配置好一切并发布——不需要配置文件、不需要流水线、不需要 YAML。数据库、域名、SSL、CDN、邮件、备份全部在一处管理。
它同时支持两种运行后端：官方托管的Openship Cloud，或你自己拥有的任意 Linux 服务器。独立开发者发布副业项目、团队运行生产环境，使用的是同一个工具、同一套界面。
从仓库结构可以印证这一设计：控制平面（API）位于 apps/api，CLI 位于 apps/cli，Web 控制台位于 apps/dashboard，路由/TLS 边缘（OpenResty）位于 apps/edge，另有桌面应用 apps/desktop 与邮件引擎 apps/email。核心业务逻辑沉淀在 packages/core 与 packages/adapters 中。
快速开始：两条官方安装路径
中文 README 给出的入门命令只有两行：
npm i -g openship openship initnpm i -g openship安装全局 CLI（需要 Node 22+），openship init则把当前目录链接到一个 Openship 项目。从源码看，init 命令会调用GET /api/projects拉取项目列表（支持交互式选择或--project <id>直连），并把projectId、name、slug、默认环境等写入当前目录的.openship/project.json，供后续openship deploy等命令读取。
如果你更偏好 Docker，官方提供了第二种方式：
git clone https://github.com/oblien/openship.git && cd openship cp .env.example .env docker compose up -d仓库根目录的 docker-compose.yml 是「SaaS / 从源码构建」形态的控制平面：postgres（存储）、redis（队列/缓存/限流）、api（:4000）、dashboard（:3001）、web（:3000，落地页），其中 postgres/redis 仅在集群内部可达，API 启动时自动执行数据库迁移，健康检查通过GET /api/health验证。
注意：根目录的
docker-compose.yml与docker/docker-compose.yml是两个不同的栈。前者是控制平面（从源码构建，不含 edge 与 Docker socket）；后者是自托管拉取镜像栈（含 OpenResty edge，见下文「自托管服务器」一节）。中文 README 中cp .env.example .env && docker compose up -d对应的正是根目录控制平面。
或者也可以从 openship.io 下载桌面应用直接使用。
三种运行形态：桌面应用、自托管服务器、Openship Cloud
官方英文 README（README.md）给出了一个清晰的决策矩阵，中文 README 的「部署到任何地方」与之呼应：
| 你的场景 | Openship 本身怎么跑 | 你的应用跑在哪里 |
|---|---|---|
| 单人、单机、不想折腾运维 | 桌面应用 | 通过 SSH 连接一台服务器，或 Openship Cloud |
| 团队，或想要 push-to-deploy / 在自己机器上托管应用 | 自托管服务器（openship up） | 本机（Compose 模式），或推到另一台服务器 / Cloud（bare 模式） |
| 什么都不想跑 | Openship Cloud | 托管沙箱，零配置 |
单人场景：桌面应用
控制平面在本地运行，通过 SSH 驱动远端服务器。无需登录、无需终端、没有对外暴露面。桌面应用本体不托管公开应用——它只是编排器。应用实际运行在你连接的服务器或 Openship Cloud 上。
团队 / 常驻场景：自托管服务器（openship up）
CLI 自带了 API 与 Web 控制台。运行openship会进入交互式向导：创建第一个管理员、绑定域名、把 Openship 安装为开机自启服务；再次运行即可管理实例。面向 CI / 无头机器，可以直接跳过向导：
openship up # 安装并以后台服务启动（开机自启 + 崩溃自动重启） openship up --public-url https://openship.example.com # 同时在你的域名上提供控制台（edge + TLS 自动处理）从 up 命令源码可以看到，openship up会自动选择运行方式：
- Linux + Docker → Compose 模式（默认）：拉起完整栈——Postgres、Redis、API、Dashboard，以及容器化的OpenResty edge（占用 :80/:443），全部来自已发布镜像。这种形态能在同一台机器上托管你部署的应用，并自动完成域名解析 + Let's Encrypt TLS。可用
--compose强制指定。 - 其他环境 → bare 模式（macOS、Windows、或无 Docker 的 Linux）：单个轻量进程 + 内嵌数据库（PGlite），作为常驻控制平面，通过 SSH 把应用部署到远端服务器或 Cloud，类似桌面应用但常驻且必须登录。可用
--bare强制指定。
自托管实例始终要求登录（即向导中创建的管理员账号）。日常管理命令：
openship open # 打开控制台 openship stop # 停止服务 openship update # 升级 openship up --foreground # 前台附着运行CLI 还支持 shell 补全（bash/zsh/fish），可写入静态补全文件或实时 source；具体方式见 README.md 的 "Shell completion" 一节。
部署一个项目
cd your-project openship init # 把当前目录链接到一个项目 openship deploydeploy 命令会根据当前目录是否为 git 仓库自动分流：git 仓库走POST /api/deployments（按分支/commit 构建）；非 git 目录则走文件夹上传流程。常用参数包括--env production|preview、--branch、--commit、--force-all、--service-ids（仅重建变更服务）、--smart-route、--watch（流式查看构建日志）。
原始 Docker Compose 自托管（不用 CLI）
高级用户也可以直接使用 docker/docker-compose.yml 自托管栈，它拉取GitHub Container Registry 上已发布的镜像（ghcr.io/oblien/*），无需任何构建工具链：
git clone https://github.com/oblien/openship.git && cd openship cp .env.example .env # 然后编辑 docker compose --env-file .env -f docker/docker-compose.yml up -d该栈为postgres + redis + api + dashboard + edge，其中 edge 是 host 网络模式的 OpenResty 容器（:80/:443），负责路由与 Let's Encrypt。仅限 Linux（依赖 host 网络）；mac/win 请用openship up（bare 模式）。api容器挂载了宿主 Docker socket，以便控制平面以宿主容器的方式构建并运行你的应用——因此它经由 socket 拥有宿主级权限，只应运行在可信主机上。
升级时在.env中固定OPENSHIP_VERSION以获得可复现的拉取，然后docker compose … pull && … up -d。若想从源码构建，追加-f docker/docker-compose.build.yml … up -d --build。
核心特性详解
中文 README 的特性表是对平台能力的官方承诺，结合仓库源码逐一展开：
内置 CI/CD
推送即部署（push-to-deploy）、预览环境、staging/生产流程、回滚。GitHub webhook 在每次推送到被跟踪分支时重新执行流水线，且 monorepo 场景下只重建被推送真正影响到的服务（智能路由，对应--smart-route/--service-ids）。
任意技术栈
Node、Python、Go、Rust、PHP、Ruby、Java、.NET、Docker、Monorepo。从 packages/core/src/languages 的 11 个语言定义文件，以及 fixtures/deploy 下的 dotnet/go/kotlin/laravel/node/python-fastapi/rust-axum/springboot 示例项目可以看到官方验证过的技术栈覆盖。README 强调：系统会读取package.json、框架配置、锁文件以及任何docker-compose.yml/openship.json来推断技术栈、包管理器、构建/启动命令与端口——零配置文件即可工作；需要精细控制时，openship.json可覆盖自动推断。
完整后端
Postgres、MySQL、MongoDB、Redis、Worker、WebSocket、存储，作为被托管应用的附属服务一并编排。
域名与 SSL
自动 Let's Encrypt、通配符证书、无限域名、自动续期。路由与 TLS 发生在应用启动之后：即使 DNS 或证书出问题，只会显示 "action required"，绝不会导致部署失败或应用下线。证书相关高级配置（ZeroSSL、私有 CA、ACME EAB）见 docs/acme.md 与 .env.example 中的OPENSHIP_ACME_*系列变量。
CDN
边缘缓存、HTTP/3、Brotli 压缩、即时清除。
邮件服务器
内置 SMTP，支持 DKIM/SPF/DMARC——无需 Mailgun 或 SES。邮件模块是一个完整子项目 apps/email，内含基于 iRedMail 的引擎（email/engine）、Web 邮箱客户端与独立数据库 packages/db-email。
备份
定时备份、数据库 + 卷、一键恢复、随时导出。备份实现分布在 packages/adapters/src/backup（33 个文件）与 CLI 的openship backup命令中。
实时监控
实时构建日志、容器指标、资源使用情况实时推送到屏幕，细节见 docs/monitoring.md。
伸缩
云端自动伸缩；自托管支持多节点（多节点集群、负载均衡 UI、私有网络列入「即将推出」路线图）。
可移植性
标准 Docker 容器——可在服务商之间自由迁移。
Docker Compose
原样部署现有的 compose 文件。
部署到任何地方
- Openship Cloud—— 托管、自动伸缩、零配置
- 任意 VPS—— Hetzner、DigitalOcean、Linode、OVH 等
- 独立服务器—— 裸机、托管机房、家庭实验室
- 多服务器—— 将负载分散到多台机器
无论部署在哪里，界面都一样。
三种界面 + 自动化接口
- 桌面应用—— 完整 GUI、实时日志、一键操作（适合单人）。
- Web 控制台—— 浏览器中的同一套界面，为团队打造。
- CLI—— 可脚本化、对 CI 友好，同时也是安装和管理自托管实例的入口。
REST API与MCP（AI 智能体协议）为自动化和工具集成收尾：MCP 端点只暴露选择加入的路由作为工具，每次调用都会重新校验权限，凭据/令牌类路由永远不会成为工具。从仓库可看到 MCP 相关实现文件（如 apps/api/src/lib/mcp-resource.ts、mcp-token.ts），CLI 也支持--json输出模式便于脚本消费。
关键配置参考（.env.example 精读）
无论自托管还是 SaaS，都由同一个 .env.example 驱动——通过CLOUD_MODE这一个开关切换形态。以下是最常用的配置分组：
模式开关
CLOUD_MODE=false：false = 自托管（默认，无计费）；true = SaaS（计费、计量、多租户）。DEPLOY_MODE=docker：docker（默认，自托管）| cloud（SaaS）。
存储与队列
DATABASE_URL：指向 Postgres；留空则使用 PGlite 内嵌数据库（仅限开发）。POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB：Compose 据此拼出DATABASE_URL。REDIS_URL：队列 + 缓存 + 限流共用。OPENSHIP_REQUIRE_REDIS=true可强制使用 Redis 后端并禁用静默的内存回退（自托管多副本建议开启）。
认证安全（上线前必改）
BETTER_AUTH_SECRET：会话密钥，用node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"生成。INTERNAL_TOKEN：内部认证令牌，任何非桌面部署都必填——API 没有它会拒绝启动。
远程访问
OPENSHIP_PUBLIC_URL：默认只信任http://localhost:3001；要从其他机器访问（反向代理或局域网），必须设置为浏览器实际使用的完整 origin，否则登录会收到403 ORIGIN_REJECTED。TRUST_PROXY=true：反向代理后面启用（代理必须设置X-Real-IP，否则所有用户共享一个限流桶）。OPENSHIP_BIND_ADDR：Compose 发布端口的网卡（默认 loopback，生产建议0.0.0.0需谨慎）。API_PORT/DASHBOARD_PORT：端口覆盖（默认 4000 / 3001）。
ACME / 证书
OPENSHIP_ACME_EMAIL、OPENSHIP_ACME_DIRECTORY_URL（默认 Let's Encrypt 生产）、OPENSHIP_ACME_KEY_TYPE=ec256|ec384|rsa2048|rsa4096、OPENSHIP_ACME_EAB_KID/OPENSHIP_ACME_EAB_HMAC_KEY（ZeroSSL 等 EAB 必须成对设置）等，完整说明见 docs/acme.md。
镜像源与版本钉住
OPENSHIP_IMAGE_REGISTRY（默认ghcr.io/oblien）与OPENSHIP_VERSION（建议钉到具体版本号如0.2.3以获得可复现升级；latest跟随最新发布）。
Docker socket 与宿主机操作通道
OPENSHIP_DOCKER_SOCKET：API 通过宿主 Docker daemon 驱动 edge 与所有应用容器。rootless Docker 下 socket 位于用户 runtime 目录（如/run/user/1000/docker.sock），可用docker context inspect --format '{{.Endpoints.docker.Host}}'确认；配置错误不会响亮失败，而是表现为「容器操作全部失败且不报路径」（对应上游 issue #482）。OPENSHIP_HOST_SSH_*系列与OPENSHIP_HOST_KEY_PATH：用于容器内无法完成的少量宿主 OS 操作（释放 :80/:443 上的外部代理、宿主系统配置、邮件引擎等）。留空不会降级为本地执行，而是直接拒绝并指明此通道；普通部署不受影响（走 docker socket）。
OAuth 与 GitHub App
GITHUB_CLIENT_ID/SECRET、GOOGLE_CLIENT_ID/SECRET：可选的第三方登录。GITHUB_AUTH_MODE=auto+GITHUB_APP_ID/SLUG/PRIVATE_KEY_BASE64/WEBHOOK_SECRET：自托管 GitHub App（无需 Openship Cloud 或 PAT），PEM 与 webhook secret 只存于服务端 env，绝不落库。
SaaS 专属（CLOUD_MODE=true）
- Oblien 三件套（
OBLIEN_CLIENT_ID/SECRET/WEBHOOK_SECRET）、BILLING_ENABLED、STRIPE_SECRET_KEY、各套餐价格 ID（STRIPE_PRICE_*）与优惠码（STRIPE_COUPON_LAUNCH50）等。价格目录定义在 packages/core/src/pricing/pricing.json，每个计划通过stripePriceEnv字段声明自己需要的 env 变量名。
项目状态、贡献与许可证
状态：核心已可用于生产，持续积极开发中；自托管免费（无计费）。即将推出：多节点集群、负载均衡 UI、私有网络、高级监控，以及可视化 CI/CD 流水线。
贡献：参见 CONTRIBUTING.md。官方提示文档仍在完善中，若发现缺失或不清楚之处，非常欢迎贡献。安全漏洞请遵循 SECURITY.md 私下披露。
许可证：Openship 依据 Apache License 2.0 授权。你可以使用、运行、修改、自托管和分发它——包括用于商业和闭源产品——只要遵守 Apache 2.0 的条款。
【免费下载链接】openshipSelf-hosted deployment platform项目地址: https://gitcode.com/GitHub_Trending/ope/openship
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
