应用

通过 SDK 和 React 创建、部署和控制 Beeuni 应用。

Apps 是项目范围内的部署，每个都有一个固定 URL，支持不可变版本、 按进程组划分的机器，以及持久化卷。根据 app.capabilities 进行分支处理。本页介绍 SDK 接口： 项目句柄上的 apps 外观接口，制品、版本、机器和卷的 调用，登录令牌、导出类型以及 React hooks。

有关模型、版本配置、来源类型、CLI、固定 URL 和冷启动唤醒行为，请阅读 Apps。

const apps = beeuni.project(projectId).apps;

apps 外观接口

制品是部署的不可变输入：

版本（部署）不可变且带有编号：

机器、扩缩容和 exec（服务端 App；没有机器的 App 返回 409 app_no_machines）：

卷（持久化磁盘）：

登录令牌（能力 member_tokens；App 缺少该能力时 返回 409 app_capability_unsupported）：

访问权限由 App 自身的授权策略决定：

部署静态站点

uploadArchive 完成整个制品握手流程：注册制品， 依据 max_bytes 检查制品，通过 PUT 上传字节，计算 SHA-256，然后 完成制品确认。

const apps = beeuni.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.beeuni.ai  queued

create 也接受机器字段：cpu、memory_gb、 disk_gb、idle_timeout_seconds 和 always_on。省略这些字段即可使用默认值。 Apps 没有月度预算：计算费用由账户额度支付。常驻运行的 服务端 App 全天候计费；按需运行的 App 仅在唤醒期间计费。 always_on: true 让服务端 App 全天候运行 （websockets、后台循环）；false 在 idle_timeout_seconds 后停止它， 并在下一个请求到来时唤醒。静态 App 没有运行时：always_on 为 false。

如果旧客户端发送 monthly_budget_usd，API 会忽略它（200，不 报错）。任何 App 响应都不包含它。

uses 按 slug 列出此 App 可以获取登录令牌并通过其绑定挂载访问的 Apps； 默认为空，update(appId, { uses }) 会替换该列表（参见 App 使用的 Apps）。

create 和 update 返回 warnings，其值始终为 []。

const app = await beeuni.project(projectId).apps.create({ slug: 'worker', name: 'Worker', always_on: true });
console.log(app.always_on, app.hosting_type); // true null (until the first deploy)

通过轮询状态等待部署完成：

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));
  }
}

状态值为 queued、validating、building、provisioning、 checking、ready、failed 和 cancelled。

部署 OCI 镜像

注册不可变镜像引用，然后声明进程命令和 公开的目标端口：

const registered = await apps.artifacts.register({
  kind: 'oci_image',
  image: 'ghcr.io/hekmat/service:2026-08-07',
});

await apps.deployments.create(app.app_id, {
  artifact_id: registered.artifact.artifact_id,
  source: {
    kind: 'oci_image',
    image: 'ghcr.io/hekmat/service:2026-08-07',
    command: ['node', 'server.js'],
    port: 3000,
    readiness_path: '/health',
  },
});

对于 oci_image，register 返回 upload: null。只有 archive 会获得 上传 URL。

CreateAppDeploymentInput 还接受 environment（非机密的运行时 值）、secrets（运行时键到项目机密名称的映射）和 config（AppReleaseConfigInput， 版本配置）。无效的 config 会返回 400 app_config_invalid，并带有 issues: [{ path, message }]；在不支持卷的运行环境中 挂载会返回 400 app_volumes_unsupported。

await apps.deployments.create(app.app_id, {
  artifact_id: registered.artifact.artifact_id,
  source: { kind: 'oci_image', image, command: ['node', 'server.js'] },
  config: {
    processes: { app: '', worker: 'node worker.js' },
    http_service: { internal_port: 3000, access: 'app', processes: ['app'] },
    mounts: [{ source: 'data', destination: '/data', initial_size_gb: 10, processes: ['app'] }],
    deploy: { release_command: 'node migrate.js' },
  },
});

读取运行时日志

let cursor = 0;
for (;;) {
  const page = await apps.deployments.logs(app.app_id, deployment.deployment_id, {
    after: cursor,
    limit: 200,
  });
  for (const entry of page.entries) console.log(entry.source, entry.line);
  cursor = page.next_cursor;
  if (page.entries.length === 0) break;
}

每个条目都包含 cursor、time、source（app、appd、caddy）以及 line。caddy 行是访问日志：方法、URI、状态、耗时和 响应头。它从不包含请求头，因为请求头携带 网关的凭据（访问者令牌和身份、提供方入口令牌）。

机器、扩缩容和卷

const apps = beeuni.project(projectId).apps;

const machines = await apps.machines.list(app.app_id);
await apps.scale(app.app_id, { worker: 3 });                     // 202: applied in the background

const { exit_code, stdout } = await apps.exec(app.app_id, { command: ['ls', '/data'] });

const [data] = await apps.volumes.list(app.app_id);
const snapshot = await apps.volumes.snapshot(app.app_id, data.volume_id);
await apps.volumes.restore(app.app_id, data.volume_id, snapshot.snapshot_id);   // project.app.admin
const copy = await apps.volumes.fork(app.app_id, data.volume_id, { name: 'data_copy' });

机器在各次发布中保留其 machine_id；每次发布都会替换其 box（instance_id）。同一时间只有一台机器挂载一个卷。恢复会生成 卷的新版本：被替换的内容会保留在历史记录中。 已挂载卷的快照可能遗漏最后约 1 秒的写入。

Convex 后端

Convex 后端是一个带有卷的普通服务器 App，使用 convex 模板创建（beeuni apps launch --template convex --name db；参见 模板 convex）。 SDK 没有 Convex 专用调用。使用 exec 从机器读取管理员密钥，并通过 uses 让 UI App 访问后端：

const db = (await apps.list()).find((a) => a.slug === 'db')!;
const { stdout } = await apps.exec(db.app_id, { command: ['sh', '-c', 'cd /convex && ./generate_admin_key.sh'] });
// The admin key controls all code and data: never log it or ship it to a browser.

await apps.update(site.app_id, { uses: ['db'] }); // the site may mint db tokens and bind to it

db.services 保存后端的 URL：http（Convex 客户端 URL）和 site（HTTP actions）。

你的 App 已经知道谁在访问

打开 Beeuni 托管 App 的人，Beeuni 已经让其登录。Apps 网关会在提供第一个字节之前验证其身份，因此你的 App 无需自己的登录流程——没有第二个密码、没有授权同意页面，也没有重定向。

在浏览器中：

import { createBeeuni, beeuniAppViewerToken } from '@beeuni/sdk';
import { useBeeuniAppViewer } from '@beeuni/sdk/react';

const beeuni = createBeeuni({
  backendUrl: '/_beeuni/api/v1',             // the gate, on your App's own origin
  getToken: beeuniAppViewerToken(),          // the viewer's own App-scoped token
});

function Header() {
  const { status, viewer } = useBeeuniAppViewer();
  return <span>{status === 'viewer' ? viewer.email : 'Signed out'}</span>;
}

浏览器在你的 App 自身的源上调用 /_beeuni/api/v1/*，绝不 直接调用 https://api.beeuni.ai/v1：API 不响应来自 App 源的 CORS 预检，因此直接调用会在浏览器中失败。网关使用访问者的 App 范围 令牌，以已登录访问者的身份，将每次调用 转发到 Beeuni API。规则如下：

• 必须有 viewer_token_scope: 'api'。否则返回 403 viewer_api_disabled。
• 仅代表网关已让其登录的访问者执行操作（通过 Beeuni 登录或访问 链接）。没有此类访问者时，返回 401 no_viewer_identity。
• 仅响应来自 App 自身源的请求。跨站请求 返回 403 cross_site_request。
• 转发 /v1/*，但 /v1/oauth/* 和 MCP 端点除外，它们返回 404。你的 App 的 Cookie 和自身的 Authorization 请求头永远不会到达 API，API 也无法在你的 App 上设置 Cookie。

在你的 App 服务器上，网关会将签名后的身份写入每个请求：

import { readAppViewer, createAppViewerBeeuni } from '@beeuni/sdk/server';

const viewer = await readAppViewer(request);
// { userId, email, name, picture, groupIds, groups, role, projectId, accountId, appId, accessMode, token }
if (!viewer) return new Response('Not found', { status: 404 });

// and, for an `api`-scoped App, act as them:
const beeuni = await createAppViewerBeeuni(request, { backendUrl });
await beeuni.projects.list();               // their projects, their role

readAppViewer 使用 BEEUNI_APP_VIEWER_SECRET 验证请求头的 HMAC， Beeuni 会在部署时将后者注入你的 App。伪造的请求头永远无法通过验证： 网关会在转发前删除客户端提供的任何副本，并使用 为每个 App 派生的密钥生成签名。

你的 App 能获知多少信息

由 App 访问策略中的一个设置决定——Beeuni 中的 Settings → Access、 beeuni apps access <app> --viewer off|identity|api，或 PATCH /projects/:id/apps/:appId/access 上的 viewer_token_scope：

令牌绝不是用户的 Beeuni 会话：它有效期为一小时，仅包含 这些范围；当 App 被删除或其 访问策略更改时，该 App 签发的每个令牌都会失效。

使用访问者令牌

• 在服务器上，每次请求都读取令牌。 网关会在 每个代理请求的 x-beeuni-app-viewer-token 中放入有效令牌。将其作为 Authorization: Bearer 发送给 Beeuni API——createAppViewerBeeuni(request) 正是这样做的。每个请求创建一个客户端；不要存储令牌。
• 访问策略更改后，旧令牌不再有效。 通过网关的下一次请求 会携带新令牌。在浏览器中，beeuniAppViewerToken() 会自行恢复：当 API 拒绝其令牌时，SDK 会重新读取 /_beeuni/viewer，并重试该调用一次。
• 访问者的角色是权限上限。 令牌只能执行 访问者在 Beeuni 中能执行的操作，绝不会更多。在具有智能体权限的项目中， member 需要获得你的 App 所启动智能体的授权：没有授权时， POST /projects/:id/sessions 返回 403 no_agent_access。向 访问者授予该智能体的权限，而不是更宽泛的角色。
• 谁具有访问者身份。 使用 Beeuni 登录打开 App 的人——或 使用访问链接打开 App 的人（链接会让其以该用户身份登录）——具有访问者身份。 password App 没有访问者身份：密码证明的是共享密钥，而不是个人身份。 public App 仅对通过访问链接进入的访客具有访问者身份； 直接访问 URL 仍为匿名。
• 它是凭据。 Beeuni 不会将请求头写入 App 的访问 日志（beeuni apps logs）。不要在自己的代码中记录该请求头。

通过自己的域名（而非 *.apps.beeuni.ai）提供服务的 App 前面没有网关 ——请在那里改用 使用 Beeuni 登录。

在每种运行时中使用同一成员身份

Beeuni 在三个地方为同一个人的身份担保：浏览器向网关请求 （/_beeuni/viewer），App 服务器读取签名请求头，而验证 登录令牌的 App（Convex 后端或你自己的服务器）会收到 Beeuni 签名的令牌。readBeeuniMember 将这些不同形式都转换为同一种 BeeuniMember，而 requireBeeuniMember 决定谁可以继续。无需 框架，也无依赖：同一套代码可在浏览器、Node、Bun、 Worker 和 Convex 函数中运行。

import {
  readBeeuniMember, requireBeeuniMember, verifyBeeuniToken,
  beeuniToken, beeuniBinding, fetchBeeuniAppViewer, BeeuniMemberError,
} from '@beeuni/sdk';

// Browser: who is looking (null when nobody).
const me = readBeeuniMember(await fetchBeeuniAppViewer());

// Browser → an App this App uses, on the same origin: its URL and a token fetcher.
const db = beeuniBinding('db');
const convex = new ConvexReactClient(db.url);
convex.setAuth(db.token);
// React: read the member with useQuery(api.members.me), never useConvexAuth() (see below).

// Browser: a token for this App itself, or for an App it uses.
const token = await beeuniToken()();
const dbToken = beeuniToken({ audience: 'db' });

// A Convex function: the runtime verified the token; enforce the rules.
const member = requireBeeuniMember(await ctx.auth.getUserIdentity(), { groups: ['Finance'] });

// A server App: verify the bearer. No options = the BEEUNI_AUTH_* env Beeuni injects.
// Any other server: pass the App's `auth` values.
const caller = await verifyBeeuniToken(bearer, { issuer: app.auth.issuer, audience: app.auth.audience, jwks: app.auth.jwks_uri });

在 React 中，不要调用 useConvexAuth()：它在普通的 ConvexProvider 下会抛出异常（它需要 ConvexProviderWithAuth，且该提供方不会 验证 beeuniBinding）。通过查询读取已登录成员：

// convex/members.ts
export const me = query({ args: {}, handler: async (ctx) => readBeeuniMember(await ctx.auth.getUserIdentity()) });

const me = useQuery(api.members.me);   // undefined: loading. null: signed out. Otherwise the member.

对于匿名调用者，readBeeuniMember 返回 null。仅在 函数必须抛出异常的地方使用 requireBeeuniMember。

requireBeeuniMember(claims, { groups, roles }) 返回成员，或者抛出 BeeuniMemberError，其 code 为 unauthenticated（没有用户，或令牌 未通过检查）或 forbidden（不属于指定群组或角色）。每个列表都表示 “其中任意一个”；群组按名称或 id 匹配；空列表不允许任何人访问。

登录令牌

每个项目有一个签发方，为每个 App 的令牌签名：iss = <API origin>/v1/projects/<projectId>，aud = 令牌所属 App 的 id， 有效期为 15 分钟。其密钥集公开于 <issuer>/jwks.json，由 <issuer>/.well-known/openid-configuration 标识。每个 App 都携带用于 验证其令牌的值：app.auth.issuer、app.auth.audience、app.auth.jwks_uri。 令牌包含 sub、email、name、picture、groups、group_ids、 role、account_id 和 project_id；智能体的令牌包含 kind: 'agent'，不包含群组或角色。

从项目或群组中移除的成员会在一个令牌有效期内失去访问权限；App 访问控制会在其下次加载页面时拒绝访问。Beeuni 群组需要 Enterprise 套餐；角色适用于所有套餐。

管理访问权限

await apps.access.update(app.app_id, {
  mode: 'restricted',
  member_ids: [memberId],
  group_ids: [groupId],
});

const preview = await apps.access.session(app.app_id);
window.open(preview.url); // valid for five minutes

AppAccessConfig 返回 password_configured，绝不返回密码或其哈希。使用 { mode: 'password', password } 设置密码。每次更新都会递增 revision，从而撤销现有的 App Cookie。

类型

以下所有类型均从 @beeuni/sdk 导出。

apps.list() 和 useProjectApps 仅返回调用者根据各 App 的访问策略可以打开的 App（私有：创建者；受限：列出的成员和群组；项目、密码和公开：项目团队）。项目管理员可以看到所有 App，因此即使创建者离开，私有 App 仍可管理。因此，每个列出的 App 的 viewer_can_access 都为 true。对调用者无法打开的 App 执行 get 时，返回 404，而非 403。应将 undefined 视为未知，而非拒绝访问。

AppAccessMode 是角色模型之上的按资源可见性设置，而不是角色。restricted 指定用户和群组——与角色模型使用的主体类型相同。参见 账户与访问权限。

DockerfileAppSource 和 OciImageAppSource 需要 command。port 是主服务的端口：仅在只有 worker 的发布版本（带有 processes 且没有服务的 config）中可以省略。StaticAppSource 和 BundleAppSource 均不接受这两项。

React hooks

@beeuni/sdk/react 导出七个用于 App 的 hook。

useProjectApps(projectId)

调用者可以打开的 App，以及其生命周期变更操作。每个变更操作成功后都会使清单缓存失效。

import { useProjectApps } from '@beeuni/sdk/react';

function AppList({ projectId }: { projectId: string }) {
  const apps = useProjectApps(projectId);
  if (!apps.data) return null;

  return (
    <ul>
      {apps.data.map((app) => (
        <li key={app.app_id}>
          <a href={app.url}>{app.slug}</a>
          <button onClick={() => apps.stop.mutate(app.app_id)}>Stop</button>
        </li>
      ))}
    </ul>
  );
}

它返回查询字段，以及 create、update、start、stop 和 remove。

useAppDeployments(projectId, appId)

不可变的部署历史，每 5 秒重新获取一次，使正在运行的构建自动更新进度。

const deployments = useAppDeployments(projectId, appId);

await deployments.deploy.mutateAsync({
  artifact_id: artifact.artifact_id,
  source: { kind: 'static', spa: true },
});
await deployments.rollback.mutateAsync(previousDeploymentId);

两个变更操作都会使部署列表和 App 清单缓存失效。

useAppDeployment(projectId, appId, deploymentId)

单个部署及其事件，包括构建日志（AppDeploymentDetail）。每 2 秒轮询一次，直到部署为 ready、failed 或 cancelled。将 null 作为 deploymentId 传入，可使其保持空闲。

const detail = useAppDeployment(projectId, appId, deploymentId);
const log = (detail.data?.events ?? [])
  .map((event) => (event.type === 'build_log' ? event.message : `[${event.type}] ${event.message}`))
  .join('\n');

一次构建会保留最前面的 2,500 行和最后面的 2,500 行。日志行以批次写入， 最迟在输出后 1 秒内写入。失败或取消的部署 会将构建日志保留 14 天。

useAppAccess(projectId, appId, options?)

访问策略和短期访问会话。两部分是独立的 查询，且均为可选。

const access = useAppAccess(projectId, appId, {
  policy: canEditAccess,
  session: app.viewer_can_access,
});

access.policy.data;  // AppAccessConfig
access.session.data; // { url, expires_at }
await access.update.mutateAsync({ mode: 'project' });

如果 App 网格将两个选项都保留为 true，则会为每个 App 发起一次策略读取和一次 会话创建；对于无权打开该 App 的成员，两者都会返回 403。

useAppMachines(projectId, appId)

App 的机器，每 5 秒轮询一次，另有 start、stop、restart、 destroy（各接受一个 machineId）和 scale（接受 { [group]: count }）。每次变更操作都会刷新机器和 App 清单。appMachinesKey(projectId, appId) 是查询键。

const machines = useAppMachines(projectId, app.app_id);
await machines.scale.mutateAsync({ worker: 2 });
await machines.restart.mutateAsync(machineId);

useAppVolumes(projectId, appId)

App 的卷，另有 snapshot（volumeId）、restore （{ volumeId, snapshotId }）、fork（{ volumeId, name, snapshotId? }）、 extend（{ volumeId, sizeGb }）和 destroy（{ volumeId, name }）。每次 变更操作都会刷新卷。appVolumesKey(projectId, appId) 是查询 键。

const volumes = useAppVolumes(projectId, app.app_id);
await volumes.snapshot.mutateAsync(volumeId);
await volumes.restore.mutateAsync({ volumeId, snapshotId });

useAppVolumeSnapshots(projectId, appId, volumeId)

一个卷的快照。将 null 作为 volumeId 传入，可使其保持空闲。

错误

import { featureDisabledKey, isFeatureDisabledError } from '@beeuni/sdk';

try {
  await beeuni.project(projectId).apps.list();
} catch (error) {
  if (isFeatureDisabledError(error)) {
    console.log(`${featureDisabledKey(error)} is off for this project`);
  }
}

你还应处理以下响应：

• slug 重复时返回 409；账户达到 App 数量上限时返回 402，并附带 app_quota_exceeded；规格超出范围时返回 400，并附带 app_machine_out_of_range。
• uses 中存在未知 slug 时返回 400 app_not_found（slugs）。
• 调用 App 不提供的功能时返回 409 app_capability_unsupported（capability）。
• 部署：400 app_config_invalid（issues）、400 app_volumes_unsupported。 回滚：409 release_not_ready。
• 机器和 exec：409 app_no_machines、404 machine_not_found、 409 machine_not_running、400 process_group_unknown、 400 scale_out_of_range、400 command_required。
• 卷：400 volume_name_invalid、volume_size_invalid、 volume_shrink_refused、volume_retention_invalid、snapshot_invalid、 confirmation_required；404 volume_not_found；409 volume_attached。

token() 返回 Cache-Control: no-store。