github-actions[bot]
40abe1e6d0
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
250 lines
9.4 KiB
Plaintext
250 lines
9.4 KiB
Plaintext
---
|
||
title: 发布
|
||
description: 将你的 Twenty 应用分发到应用市场，或进行内部部署。
|
||
---
|
||
|
||
<Warning>
|
||
应用目前处于 Alpha 测试阶段。 该功能可用，但仍在演进中。
|
||
</Warning>
|
||
|
||
## 概览
|
||
|
||
一旦你的应用已[在本地构建并完成测试](/l/zh/developers/extend/apps/building)，你可以通过两种方式进行分发：
|
||
|
||
* **发布到 npm** — 将你的应用在 Twenty 应用市场上架，供任何工作区发现并安装。
|
||
* **部署 tar 包** — 直接将你的应用上传到特定的 Twenty 服务器，以供内部或私有使用。
|
||
|
||
两种路径都从同一个**构建**步骤开始。
|
||
|
||
## 构建你的应用
|
||
|
||
`build` 命令会编译你的 TypeScript 源码，转译逻辑函数和前端组件，并生成一个描述你应用内容的 `manifest.json`：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty build
|
||
```
|
||
|
||
输出将写入 `.twenty/output/`。 此目录包含分发所需的一切：已编译的代码、资源、清单，以及你的 `package.json` 副本。
|
||
|
||
要同时创建一个 `.tgz` 压缩包（由部署命令在内部使用，或用于手动分发）：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty build --tarball
|
||
```
|
||
|
||
## 发布到 npm
|
||
|
||
发布到 npm 可让你的应用在 Twenty 应用市场中被发现。 任何 Twenty 工作区都可以直接通过 UI 浏览、安装和升级应用市场中的应用。
|
||
|
||
### 要求
|
||
|
||
* 一个 [npm](https://www.npmjs.com) 账户
|
||
* 在你的 `package.json` 的 `keywords` 数组中**必须**包含 `twenty-app` 关键字
|
||
|
||
### 添加所需关键字
|
||
|
||
Twenty 市场通过在 npm 注册表中搜索带有 `twenty-app` 关键字的包来发现应用。 将其添加到你的 `package.json`：
|
||
|
||
```json filename="package.json"
|
||
{
|
||
"name": "twenty-app-postcard-sender",
|
||
"version": "1.0.0",
|
||
"keywords": ["twenty-app"],
|
||
...
|
||
}
|
||
```
|
||
|
||
<Note>
|
||
该市场会在 npm 注册表中搜索 `keywords:twenty-app`。 没有此关键字，即使包名带有 `twenty-app-` 前缀，你的包也不会出现在市场中。
|
||
</Note>
|
||
|
||
### 步骤
|
||
|
||
1. **构建你的应用：**
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty build
|
||
```
|
||
|
||
2. **发布到 npm：**
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty publish
|
||
```
|
||
|
||
这会在 `.twenty/output/` 目录下运行 `npm publish`。
|
||
|
||
要在特定的 dist-tag（例如 `beta` 或 `next`）下发布：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty publish --tag beta
|
||
```
|
||
|
||
### 应用市场的发现机制如何运作
|
||
|
||
Twenty 服务器会**每小时**从 npm 注册表同步其市场目录：
|
||
|
||
1. 它会搜索所有带有 `keywords:twenty-app` 关键字的 npm 包
|
||
2. 对于每个包，它会从 npm CDN 获取 `manifest.json`
|
||
3. 应用的元数据（名称、描述、作者、徽标、屏幕截图、类别）将从清单中提取，并显示在市场中
|
||
|
||
发布后，你的应用最多可能需要一小时才会出现在市场中。 要立即触发同步，而无需等待下一次每小时同步：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty catalog-sync
|
||
```
|
||
|
||
要指定特定的远程：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty catalog-sync -r production
|
||
```
|
||
|
||
市场中显示的元数据来自你在应用源代码中调用的 `defineApplication()` —— 诸如 `displayName`、`description`、`author`、`category`、`logoUrl`、`screenshots`、`aboutDescription`、`websiteUrl` 和 `termsUrl` 等字段。
|
||
|
||
### CI 发布
|
||
|
||
脚手架项目包含一个 GitHub Actions 工作流，会在每次发版时自动发布：
|
||
|
||
```yaml filename=".github/workflows/publish.yml"
|
||
name: Publish
|
||
on:
|
||
release:
|
||
types: [published]
|
||
|
||
permissions:
|
||
contents: read
|
||
id-token: write
|
||
|
||
jobs:
|
||
publish:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- uses: actions/setup-node@v4
|
||
with:
|
||
node-version: "24"
|
||
registry-url: https://registry.npmjs.org
|
||
- run: yarn install --immutable
|
||
- run: npx twenty build
|
||
- run: npm publish --provenance --access public
|
||
working-directory: .twenty/output
|
||
env:
|
||
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||
```
|
||
|
||
对于其他 CI 系统（GitLab CI、CircleCI 等），同样适用以下三条命令：`yarn install`、`yarn twenty build`，然后在 `.twenty/output` 目录下执行 `npm publish`。
|
||
|
||
<Tip>
|
||
**npm provenance** 可选，但建议启用。 使用 `--provenance` 发布会在你的 npm 列表中添加可信徽章，使用户可以验证该包是由公共 CI 流水线中的特定提交构建的。 有关设置说明，请参见 [npm provenance 文档](https://docs.npmjs.com/generating-provenance-statements)。
|
||
</Tip>
|
||
|
||
## 部署到服务器（tar 包）
|
||
|
||
对于你不希望公开的应用（专有工具、仅供企业使用的集成或实验性构建），你可以将 tar 包直接部署到某台 Twenty 服务器。
|
||
|
||
### 先决条件
|
||
|
||
在部署之前，你需要配置一个指向目标服务器的远程。 远程会将服务器 URL 和身份验证凭据本地存储在 `~/.twenty/config.json` 中。
|
||
|
||
添加远程：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty remote add --url https://your-twenty-server.com --as production
|
||
```
|
||
|
||
对于本地开发服务器：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty remote add --local --as local
|
||
```
|
||
|
||
对于非交互式环境，你也可以使用 API 密钥进行身份验证：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
|
||
```
|
||
|
||
管理你的远程：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty remote list # List all configured remotes
|
||
yarn twenty remote switch prod # Set the default remote
|
||
yarn twenty remote status # Show active remote and auth status
|
||
yarn twenty remote remove old # Remove a remote
|
||
```
|
||
|
||
### 部署
|
||
|
||
一步构建并将你的应用上传到服务器：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty deploy
|
||
```
|
||
|
||
这会使用 `--tarball` 构建应用，然后通过 GraphQL 多部分上传将该 tar 包上传到默认远程。
|
||
|
||
部署到特定远程：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty deploy -r production
|
||
```
|
||
|
||
### 共享已部署的应用
|
||
|
||
通过 tar 包分发的应用不会出现在公共市场中，因此同一服务器上的其他工作区无法通过浏览发现它们。 要共享已部署的应用：
|
||
|
||
1. 前往 **Settings > Applications > Registrations** 并打开你的应用
|
||
2. 在 **Distribution** 选项卡中，点击 **Copy share link**
|
||
3. 将此链接分享给其他工作区的用户 — 它会将他们直接带到该应用的安装页面
|
||
|
||
该分享链接使用服务器的基础 URL（不包含任何工作区子域），因此适用于该服务器上的任意工作区。
|
||
|
||
### 版本管理
|
||
|
||
要发布更新：
|
||
|
||
1. 更新 `package.json` 中的 `version` 字段
|
||
2. 运行 `yarn twenty deploy`（或 `yarn twenty deploy -r production`）
|
||
3. 已安装该应用的工作区会在其设置中看到可用的升级
|
||
|
||
## 安装应用
|
||
|
||
一旦应用已发布（npm）或已部署（tar 包），各工作区即可通过 UI 进行安装：
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty install
|
||
```
|
||
|
||
或者在 Twenty UI 的 **Settings > Applications** 页面中浏览并安装来自市场或通过 tar 包部署的应用。
|
||
|
||
## 应用分发类别
|
||
|
||
Twenty 会根据分发方式将应用归为三类：
|
||
|
||
| 类别 | 工作原理 | 在应用市场中可见？ |
|
||
| ------------- | -------------------------------------------------- | --------- |
|
||
| **开发** | 通过 `yarn twenty dev` 运行的本地开发模式应用。 用于构建和测试。 | 否 |
|
||
| **已发布（npm）** | 发布到 npm 且包含 `twenty-app` 关键字的应用。 在应用市场上架，供任何工作区安装。 | 是 |
|
||
| **内部（tar 包）** | 通过 tar 包部署到特定服务器的应用。 仅通过分享链接对该服务器上的工作区可用。 | 否 |
|
||
|
||
<Tip>
|
||
在构建你的应用时，从**开发**模式开始。 准备就绪后，选择用于广泛分发的**已发布**（npm），或用于私有部署的**内部**（tar 包）。
|
||
</Tip>
|
||
|
||
## CLI 参考
|
||
|
||
| 命令 | 描述 | 关键选项 |
|
||
| --------------------------- | ---------------- | ------------------------------------------- |
|
||
| `yarn twenty build` | 编译应用并生成清单 | `--tarball` — 同时创建一个 `.tgz` 包 |
|
||
| `yarn twenty publish` | 构建并发布到 npm | `--tag <tag>` — npm 分发标签（例如 `beta`、`next`） |
|
||
| `yarn twenty deploy` | 构建并将 tar 包上传到服务器 | `-r, --remote <name>` — 目标远程 |
|
||
| `yarn twenty catalog-sync` | 在服务器上触发市场目录同步 | `-r, --remote <name>` — 目标远程 |
|
||
| `yarn twenty install` | 在某个工作区安装已部署的应用 | `-r, --remote <name>` — 目标远程 |
|
||
| `yarn twenty dev` | 监听并同步本地更改 | 使用默认远程 |
|
||
| `yarn twenty remote add` | 添加服务器连接 | `--url`，`--token`，`--as`，`--local`，`--port` |
|
||
| `yarn twenty remote list` | 列出已配置的远程 | — |
|
||
| `yarn twenty remote switch` | 设置默认远程 | — |
|
||
| `yarn twenty remote status` | 显示连接状态 | — |
|
||
| `yarn twenty remote remove` | 移除远程 | — |
|