不想把部署权交给黑箱 Agent：用 Stackdome 把应用、数据库与回滚写进一个 Stackfile
AI 编码 Agent 已经很擅长修改仓库，但“把它部署出去”仍是另一类问题：它需要理解镜像、环境变量、数据库、域名、日志和失败后的回退路径。若这些信息散落在聊天记录、云控制台和某位同事的 shell 历史中，Agent 即使成功把服务推上线，也很难说明部署到底包含了什么；下次改动更难复现。
Stackdome 的思路是把交付对象从“某个容器”提升为一个声明式应用栈。它是一个可自托管的 Railway、Render、Heroku 替代方案：服务、数据库、卷与它们的连接关系写入 stackfile.yaml；同一份文件可由 CLI、可视化 Canvas 或支持 Agent Skills 的编码 Agent 使用。项目主仓库采用 AGPL-3.0，独立的 stackdome CLI 则标注为 MIT。
这篇文章不把它当作“让 Agent 一键上线”的魔法按钮，而是讨论怎样把 Agent 放进可审阅的部署闭环：先生成配置，后验证；先把凭据留在平台，后触发发布；用状态、日志和回滚替代口头确认。
为什么部署文件比一段成功提示更重要
Agent 的一句“已部署”通常遗漏三个关键事实。
第一，改动的边界不清楚。一个 Web 服务可能还依赖 Redis、Postgres、持久化卷和迁移任务；只更新 Web 镜像不意味着整个应用处于一致状态。
第二，配置很难被审查。把数据库连接串或 API Key 直接写进 Agent 提示词，既不可审阅，也扩大了凭据暴露面。Stackdome 的 Stackfile 只引用已存在的 secret 和 addon，不能在文件里创建它们；这使配置文件可以进入代码审查，而敏感值仍留在平台侧。
第三，失败路径没有被产品化。能访问某个 URL 并不等于发布健康。真正有用的交付流程应有明确的终态、可读日志，以及回退到前一版本的能力。
Stackdome 将这些要素聚合为 Stack：资源可以是 Service、StatefulService、Worker、Job 或 CronJob。一个资源必须在 image 与 build 之间二选一；端口、依赖、卷、环境变量和公开入口都在同一配置里描述。文档还说明未知字段会在解析阶段报错，而不是悄悄被忽略——这对 Agent 生成 YAML 尤其重要。
从一个最小应用栈开始
下面的例子不是完整生产模板，但展示了“公开 API + 内部 Redis + 持久化卷”的边界。镜像名、端口和环境变量应按自己的应用替换。
name: demo-api
resources:
api:
image: ghcr.io/example/demo-api:1.0.0
ports:
- name: http
port: 3000
public: true
subdomain: api
env:
APP_ENV: production
PUBLIC_URL: "{{ self.public_url }}"
CACHE_URL: "redis://{{ redis.host }}:6379"
depends_on:
- redis
redis:
image: redis:7-alpine
workload_type: StatefulService
ports:
- name: redis
port: 6379
volumes:
- name: redis-data
path: /data
volumes:
redis-data:
size: 1Gi
这里有几个容易被忽略的约束。api 只有一个端口，因此可以用 {{ self.public_url }} 取得自身公开 URL；跨资源引用则使用 {{ redis.host }}。如果一个资源有多个命名端口，引用必须带上端口名，避免把网络连接指向错误端口。卷必须先在顶层声明，挂载一个未声明的卷会被校验器拒绝。
数据库场景也应采用同样的分层：把密码放进已创建的 secret 或 Postgres addon，而不是提交到 Stackfile。对需要执行 DDL 的迁移，可单独设为 Job，将运行中的应用与一次性迁移职责分开；不要让长期运行的 Web 进程在每次重启时“顺便”做不可预测的迁移。
自托管控制面：先理解前提，再运行安装器
如果不希望平台交付依赖云端 alpha 容量，可以把 Stackdome 安装到自己的 Linux 服务器。官方安装文档给出的快速入口是：
curl -fsSL https://get.stackdome.com/install.sh | sudo sh
在自动化中，直接把远端脚本交给 root 并不理想。官方文档也提供了先下载、做 shell 语法检查、再显式传参和要求 JSON 输出的模式：
installer=$(mktemp) curl -fsSL https://get.stackdome.com/install.sh -o "$installer" sh -n "$installer" sudo sh "$installer" \ --email "admin@example.com" \ --output json \ --credentials-file /root/stackdome-credentials.json
安装器要求 Linux amd64 或 arm64、root 权限、可用的 curl，并会检查 80、443、6443 端口。文档将 2 vCPU、4 GB 内存、根分区 20 GB 可用空间列为实际容量下限。它会在服务器上部署 k3s 和 Helm，在集群中创建控制面、平台数据库、镜像仓库及相关资源。这里的关键取舍是：你获得了基础设施控制权和可持续容量，也同时需要承担 DNS、入口端口、服务器补丁和控制面凭据保护责任。
尤其要注意，安装器创建的 API 服务账户拥有跨命名空间的集群级权限，文档明确提示要保护 stackdome-control-plane 中的长生命周期 token Secret。自托管并不是“更安全”的自动同义词；它只是把安全边界移回了你的运维责任范围。
将 Agent 限制在可验证的发布流水线里
CLI 是把声明式文件落地的合适接口。安装后，先登录并确认当前上下文，再初始化、验证、发布：
stackdome login --url "https://stackdome.example.com" --token "$STACKDOME_TOKEN" stackdome ctx -o json stackdome init stackdome validate stackdome deploy --wait -o json stackdome status -o json
stackdome init 会在发现 docker-compose.yaml 时尝试转换，否则写入起始 Stackfile；真正应交给 Agent 的工作是补全这个文件并提交 diff，而不是跳过审查直接执行部署。stackdome validate 应成为必经门：它会在请求进入服务器前检查字段、资源数量、端口范围、依赖关系、卷引用与输出引用。
stackdome deploy --wait 的价值在于它会等待发布进入终态；根据 CLI 文档，未达到 Released 会以非零状态退出。CI 或 Agent 不该把“命令已发送”当作成功，而应检查退出状态与 JSON 结果。出现问题时，使用 stackdome logs 查看运行或构建日志，必要时用 stackdome rollback 回到先前 release，而不是让 Agent 在生产环境反复猜测修复。
这里可以进一步把“发布完成”的判断拆成四层。第一层是配置层：validate 已通过，且生成的 Stackfile diff 经人或受保护分支审核。第二层是控制面层：deploy --wait 的退出码与结构化结果表明 release 达到终态。第三层是运行层：用 status -o json 查看每个资源是否已收敛，再用 logs 针对异常资源读取实际错误，而不是只看网页是否打开。第四层才是业务层：对外部 URL 发起健康检查，必要时跑登录、写入或队列消费等最小冒烟测试。四层信号分别覆盖“声明正确”“平台接受”“工作负载运行”和“用户路径可用”；把它们混成一个“部署成功”布尔值，正是自动化最常见的盲点。
回滚也应提前演练，而不是等事故发生才第一次尝试。先在非生产环境记录一次正常 release，再制造可控失败，确认团队知道如何定位 release、读取构建日志、执行回滚并复核公开入口。对有状态系统尤其如此：应用镜像可以回退，并不自动意味着数据库 schema 或异步任务副作用也能逆转。把迁移设计成兼容旧版本、把破坏性操作单独审批，通常比依赖任何平台的“一键回滚”更可靠。
Agent Skills 用户还可安装官方部署 skill：
npx skills add stackdome/skills
随后让 Agent 在仓库内生成、验证并部署 Stackfile。但 API token 应按最小权限发放，通过 STACKDOME_TOKEN 等环境变量注入；不要把账户密码交给 Agent，也不要把 token 写入仓库或 Stackfile。
适用边界：它解决交付编排，不替你设计架构
Stackdome 更适合已有容器化应用、希望把多资源部署收敛为 Git 可审阅配置的团队或个人。它特别适合 Agent 参与开发、但人仍希望保留发布边界与回滚权的情形。
反过来，如果你只维护一个静态站点，或团队已经深度标准化在另一套 Kubernetes/GitOps 控制面上，再引入一层平台未必划算。当前官方文档也标明 Cloud 仍处于容量有限的 alpha 阶段；对稳定环境，应先验证自托管要求、域名与权限模型，再决定是否纳入正式交付链路。
把交付写进 Stackfile 的真正收益，不是让 Agent 更快按下部署按钮，而是让每次上线留下可阅读、可验证、可回退的事实记录。它也让部署讨论回到代码审查能够处理的层面：哪些资源会被创建或替换、哪些端口会公开、哪些数据需要持久化、失败后由谁确认回滚。对快速迭代的小团队而言，这种清晰度往往比多一个自动化入口更有价值。