---
title: 安装与运行 Teloa
description: 安装 Teloa 社区版 0.2.8 正式版，了解升级、运行位置和权限范围。
lastVerified: 2026-10-23
---

# 1.4 安装与运行 Teloa


Teloa 的服务可以在本机直接运行，也可以放入容器。两种方式都通过浏览器使用现有 Web 界面，区别在于工具在哪里执行、能访问哪些文件和程序。

## 选择运行方式

本文对应 **0.2.8 正式版**，已通过 [GitHub Release](https://github.com/teloa-ai/teloa/releases/tag/v0.2.8)、[npm](https://www.npmjs.com/package/@teloa/cli/v/0.2.8) 和 [Docker Hub](https://hub.docker.com/r/teloa/teloa) 发布。已有安装升级时保留原安装身份与数据。

- **npm 原生安装**：无需源码或编译，应用和智能体引擎 DSH 在本机 Node.js 中运行，默认使用 Docker PostgreSQL。按下文安装。
- **Docker Hub + Compose**：应用、智能体引擎与数据库均在容器内，使用下文的版本配置。目标平台为 Linux ARM64，amd64 尚未验证；最终镜像以发行回执为准。
- **源码运行**：适合开发和修改，按[本地开发指引](https://docs.teloa.ai/v/0.2.8/markdown/develop/local-development.md)启动。源码根目录仍可执行 `docker compose up -d --build` 自行构建。

需要调用自己电脑上的程序时，选择原生运行。容器中的 shell 执行容器内的程序；挂载指定文件夹只提供文件访问，不等于控制本机应用。部署在远端服务器上也不会自动获得个人电脑的文件访问权。

## 从 GitHub Release 原生安装

npm 安装器提供现有开源 Web 的安装与启停命令，用户仍在浏览器中工作。Teloa 和智能体引擎原生运行，数据库默认由 Docker 管理，也可选择已有的本机 `teloa` 专用 PostgreSQL，不连接任意远程数据库。

最低支持 **Node.js 22.19 及以上的 22.x 或 24.x** 与 **npm 11.12.1 及以上的 11.x**；Node.js 22 自带的 npm 10 需先升级。0.2.8 的已验收安全基线是 **Node.js 24.22.1**（或 22.23.4 及以上的 22.x），低于基线的 22.x 应先升级。

所有方式都需要自行配置模型；使用远程模型时，准备相应服务的 API 密钥。原生安装保留工具授权、工作目录与审批边界，桌面或浏览器操作需要另外接入相应工具。平台支持以实际验收范围为准。

### 1. 安装并启动

将精确版本安装到独立命令目录，选择空闲端口。以下为 `0.2.8` 的安装命令；先运行 `up` 初始化，再核对运行状态：

```sh
npm install --prefix ./teloa-command --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.8/teloa-cli-0.2.8.tgz
./teloa-command/node_modules/.bin/teloa up --port 3101
./teloa-command/node_modules/.bin/teloa doctor
./teloa-command/node_modules/.bin/teloa status
```

可用[发行页](https://github.com/teloa-ai/teloa/releases/tag/v0.2.8)的 `SHA256SUMS` 核对下载。也可从 npm 安装同版：`npm install --ignore-scripts @teloa/cli@0.2.8`。

下文 `teloa` 指该命令目录中的 `node_modules/.bin/teloa`。默认安装目录为 `~/.teloa`；新安装可通过 `--home`、`--port`、`--workspace` 指定目录和端口。浏览器未自动打开时运行 `teloa open`。进入后[配置模型](https://docs.teloa.ai/v/0.2.8/markdown/start/models.md)，再[新建项目](https://docs.teloa.ai/v/0.2.8/markdown/guides/projects.md)。

使用已有 PostgreSQL 时，仅接受 `localhost` 或 `127.0.0.1` 上名为 `teloa` 的独立数据库；首次安装必须为空库，不接管其他安装。通过 `--database-config` 提供包含 `connectionString` 的 JSON 文件，权限应为 `0600`；不要把连接凭据放入命令行或公开日志。

更新 npm 命令包不会自动替换运行中的应用。从已有的 0.2.6、0.2.7 等正式版（以及 Alpha/Beta）升级时，保留原 `--home`，使用下方 0.2.8 命令包先停止，再运行 `teloa upgrade --to 0.2.8`；升级会自动备份并核对候选就绪，不要覆盖程序目录或重新初始化原数据库。0.2.7 到 0.2.8 已验证保留任务与身份。

将已有安装（例如上一稳定版或 `0.2.0-alpha.7`）升级到 0.2.8 时，先把 `0.2.8` 命令包安装到新的命令目录，再用它停止原安装并升级。自定义安装继续传入原 `--home`：

```sh
npm install --prefix ./teloa-command-028 --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.8/teloa-cli-0.2.8.tgz
./teloa-command-028/node_modules/.bin/teloa stop
./teloa-command-028/node_modules/.bin/teloa upgrade --to 0.2.8
./teloa-command-028/node_modules/.bin/teloa status
```

`--to` 等于当前命令包版本时，升级使用该命令包作为候选；其他版本仍从 npm 注册表取得。升级保留原安装身份、端口、工作目录和数据，并在切换前自动备份。只运行新命令包的 `up` 不会替换原安装，会继续启动原版本并提示升级命令。

### 2. 环境检查

```sh
teloa doctor
teloa doctor --json
```

尚未初始化也能检查 Node、PATH 中的 npm 与真实终端沙箱，不会创建安装目录或启动数据库。任何检查未通过时退出码为 `1`，文本会给出建议，JSON 中对应项的 `ok` 为 `false` 并带 `remedy`。已有安装还会检查运行依赖、目录、数据库和服务。

Linux 受限终端需要可运行的 bubblewrap 或支持 Landlock 的内核；某些 Docker 或模拟环境不具备条件。请修复环境后重跑检查，不要关闭沙箱。诊断通过后仍需[配置并测试模型](https://docs.teloa.ai/v/0.2.8/markdown/start/models.md)；Web 就绪不等于终端任务或模型已可用。更多情况见[故障排查](https://docs.teloa.ai/v/0.2.8/markdown/deploy/troubleshooting.md)。

### 3. npm 安装的停止与继续

使用同一命令目录中的 CLI。停止后保留安装数据：

```sh
teloa status
teloa stop
teloa up
```

停止前先处理运行中的工作；使用自定义安装目录时，继续传入原来的 `--home`。更换版本前先看[备份与升级](https://docs.teloa.ai/v/0.2.8/markdown/deploy/backup.md)。

## 使用 Docker Compose

以下步骤会把 Teloa 和 PostgreSQL 放入容器，数据保存在持久卷中。本机无需安装 Node.js、pnpm 或 OrbStack。

### 开始前

- 安装并启动 [Docker Desktop](https://docs.docker.com/desktop/) 或装有 Docker Compose 的 [Docker Engine](https://docs.docker.com/engine/install/)。
- 使用 Linux ARM64 环境。下文镜像与配置固定为 `teloa/teloa:0.2.8`；amd64 尚未验证。
- 网络能够下载镜像和软件依赖；模型由你自行配置，远程服务需要相应 API 密钥。

新建一个目录，下载[本版本 Compose 配置](https://docs.teloa.ai/v/0.2.8/downloads/0.2.8/compose.yaml)。配置沿用密码初始化、独立数据库与持久卷，不需要编译源码。

```sh
docker info
docker compose version
```

前者应返回运行中的引擎信息，后者显示 Compose 版本。使用当前维护的 Docker，确保支持健康检查和初始化服务的依赖条件。

### 启动

在新的目录中执行：

```sh
mkdir teloa-free
cd teloa-free
curl --fail --location https://docs.teloa.ai/downloads/0.2.8/compose.yaml --output compose.yaml
docker compose pull
docker compose up -d --no-build
```

首次启动使用正式镜像，依次生成数据库口令、初始化数据库并启动 Teloa。口令保存在独立卷中，不需要填写演示密码。

### 查看状态

```sh
docker compose ps
```

等待 `db` 与 `app` 健康。`init` 是一次性初始化服务，成功退出属于正常行为。持续重启时先[检查错误](https://docs.teloa.ai/v/0.2.8/markdown/deploy/troubleshooting.md)，不要删除数据卷。

默认 Web 端口为本机 `3100`，数据库端口不开放到容器外。已有服务占用时，在本目录 `.env` 中填写 `TELOA_PORT=3101`，再启动；不要结束无关服务。

### 打开认证链接

```sh
docker compose logs --tail=50 app
```

在自己的终端找到本次启动输出的完整认证链接。更改过端口时，将链接的端口改为你设置的端口，并保留完整认证参数。

重启后使用新链接。认证链接不是模型密钥，也不要把含认证参数的日志贴到公开问题中。

### 开始工作

首次进入时可能会提示添加 API 密钥；可以当场配置，也可以选择“稍后配置”，再进入 **设置 > 模型**。按[模型指南](https://docs.teloa.ai/v/0.2.8/markdown/start/models.md)验证一次回应。页面可用和模型可用是两个不同结果。

[![未配置聊天模型时的模型选择器。需要先到设置中保存自己的模型凭据。](https://docs.teloa.ai/v/0.2.8/assets/screenshots/model-key-024.5d7394d174ce.png)](https://docs.teloa.ai/v/0.2.8/assets/screenshots/model-key-024.5d7394d174ce.png)

*0.2.4 真实界面，示例数据。未配置聊天模型时的模型选择器。需要先到设置中保存自己的模型凭据。*

接着[完成第一项任务](https://docs.teloa.ai/v/0.2.8/markdown/start/first-task.md)或[组建第一支团队](https://docs.teloa.ai/v/0.2.8/markdown/start/first-team.md)。初始环境可能为空，不要求先导入演示数据。

### 停止与继续

```sh
docker compose stop
docker compose start
```

数据保留在持久卷中。电脑休眠、关机或 Docker 退出后，本机任务和自动化无法继续执行。升级前先[备份](https://docs.teloa.ai/v/0.2.8/markdown/deploy/backup.md)；修改源码请看[本地开发](https://docs.teloa.ai/v/0.2.8/markdown/develop/local-development.md)。