企业官网建设流程全解析

如何用 Kortix Apps 把静态站点部署到稳定 URL 并回滚版本

【免费下载链接】agentpressThe open-source AI Management System项目地址: https://gitcode.com/GitHub_Trending/ag/agentpress

如果你已经有一个构建好的静态站点（纯 HTML/CSS/JS 目录，或 Vite、Next.jsoutput: 'export'生成的dist/、out/），希望它挂在一个永不改变的 URL 上、且出问题时能退回上一个版本，Kortix 的 Apps 就是做这件事的：App 创建时分配一个稳定主机名，之后每次部署都是一个不可变、带版本号的记录，失败的部署永远不会替换线上流量。本文路径基于kortixCLI，适用环境是 macOS 和 Linux（安装脚本只提供这两个平台的预构建二进制，Windows 不受支持），要求已登录 Kortix 账号且对项目持有project.customize.write权限。

准备条件：装 CLI、登录、打开 Apps 开关

1. 安装 CLI（macOS / Linux）：

curl -fsSL https://kortix.com/install | bash

2. 登录，kortix login会打开浏览器完成认证，然后让你选定账号和默认项目：

kortix login

3. 打开 Apps 特性开关。Apps 是一个 feature flag，稳定性为stable但默认关闭，必须在项目粒度上显式打开，否则所有 Apps 路由都会返回403，code: "feature_disabled"：

kortix projects features enable apps

也可以在 Web 界面的Settings → Experimental里打开Apps开关。命令行里可以用kortix projects features查看每个 flag 的 key、状态、来源和稳定性，--json输出完整目录。

部署静态站点：最短主路径

先本地完成站点构建，然后在已链接项目的目录里执行deploy：

kortix apps deploy dist --slug docs --access project

• dist是要部署的静态资源目录，Kortix 会把它打包成.tar.gz上传；
• --slug docs指定 App 名并决定 URL 中的 slug；同一项目内 slug 重复会返回409；
• --access project让任何能读该项目的人都可以打开这个 App。新 App 默认是private（仅创建者可见），所以除非只想自己验证，建议在部署时就把访问模式设好。访问模式共五种：private、project、restricted、public、password。

deploy在首次使用时创建 App，注册不可变 artifact（路径则上传.tar.gz，--image则记录镜像引用），构建它，并默认阻塞到稳定 URL 就绪为止。等待预算由--wait-seconds控制，默认1200秒；只有当另一个进程负责跟踪状态时才用--no-wait。

注意区分源类型：static和bundle不需要--command/--port；只有dockerfile和oci_image强制要求这两个参数，本文的静态站点走static即可。

可选：把本地部署默认值写进kortix.yaml的apps.<name>块，再用kortix apps deploy --manifest-app docs选中它。显式命令行参数总是优先于块中的值（文档示例）：

apps: docs: path: docs/dist type: static spa: true readiness_path: / idle_timeout_seconds: 300 monthly_budget_usd: 5

验证部署结果

稳定 URL 在 App 创建时分配，之后永不改变。Kortix Cloud 上主机名形如<env>-<slug>-<route-key>.apps.kortix.com；自托管部署则从KORTIX_APPS_BASE_DOMAIN配置的通配域名提供服务。

部署尚未完成时（queued、validating、building、provisioning、checking、activating 或 starting），访问该 URL 会看到：

• 浏览器：品牌化的状态页，HTTP202，retry-after: 3，每 3 秒 meta 刷新；
• 机器客户端：202加 JSON——冷启动场景返回{ code: "app_starting" }与retry-after: 3。

看到真实页面内容，即表示就绪。命令行侧用以下命令核对 App 与其部署历史（支持--json供脚本使用）：

kortix apps show docs # 查看 App 和它的 deployments kortix apps list # 列出项目的所有 Apps

如果某次部署失败，稳定 URL 返回503、code: "app_deployment_failed"（被取消则是app_deployment_cancelled）；失败部署不会顶掉仍在服务的旧版本，这正是可以安全回滚的前提。

回滚到旧版本

每次部署拿到该 App 的下一个版本号并且不可变；部署记录同时保存源类型、托管 provider、构建与运行时规格、尝试次数、错误码，以及操作者信息（created_by、actor_type、agent 部署时的source_session_id）。

回滚操作分两步：

1. 用kortix apps show docs列出部署历史，确认要退回的目标 deployment id 处于 ready 状态；
2. 把流量切过去：

kortix apps rollback docs <deployment-id>

<deployment-id>替换为第 1 步选定的部署 id。回滚只接受 ready 的部署；执行顺序是先启动目标部署的运行时，再停掉当前的。如果目标启动失败，当前部署继续提供服务，流量不会中断。

日常运维还有两个配套命令：kortix apps stop <id|slug>立即挂起计算（下一个授权请求会自动唤醒沙箱，不需要手动预热），kortix apps start <id|slug>在流量到达前先预热。

用 SDK 走同样的流程（可选分支）

如果你的发布流程已经在 TypeScript 里，SDK → Apps 提供了等价能力：

const apps = kortix.project(projectId).apps; const app = await apps.create({ slug: 'docs', name: 'Docs' }); const artifact = await apps.artifacts.uploadArchive(tarGzBytes, { onProgress: (uploaded, total) => console.log(`${uploaded}/${total}`), }); const deployment = await apps.deployments.create(app.app_id, { artifact_id: artifact.artifact_id, source: { kind: 'static', spa: true }, }); console.log(app.url, deployment.status); // https://…apps.kortix.com queued

uploadArchive一次完成注册、max_bytes校验、上传字节、计算 SHA-256 和 finalize。部署状态取值为queued、validating、building、provisioning、checking、ready、failed、cancelled，轮询apps.deployments.get直到ready（文档示例）：

async function waitForReady(appId: string, deploymentId: string) { for (;;) { const { deployment } = await apps.deployments.get(appId, deploymentId); if (deployment.status === 'ready') return deployment; if (deployment.status === 'failed' || deployment.status === 'cancelled') { throw new Error(deployment.error ?? deployment.error_code ?? deployment.status); } await new Promise((resolve) => setTimeout(resolve, 2000)); } }

回滚同样是单次调用：await apps.rollback(appId, previousDeploymentId);。

限制与报错对照

机器与预算的默认值和允许范围：

通过kortix apps set修改机器、--idle-timeout或--budget时，只发送你实际传入的 flag，且需要项目写权限；这类变更作用于下一次部署，不改变正在运行的运行时。

完整的命令清单（list/create/deploy/set/show/logs/start/stop/rollback/access/access-link/delete，其中--project、--host、--json对每个子命令都可用）见 Apps 文档；CLI 的全局参考见 CLI，新账号从零走通的完整路径见 Quickstart。

【免费下载链接】agentpressThe open-source AI Management System项目地址: https://gitcode.com/GitHub_Trending/ag/agentpress