---
title: 安装与运行 Teloa
description: 选择源码或 Docker 运行方式，了解 npm 安装计划与本机操作范围。
lastVerified: 2026-09-23
---

# 1.2 安装与运行 Teloa

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

## 选择运行方式

- **源码原生运行 · 当前可用**：应用和 Harness 在本机 Node.js 中运行，默认使用 Docker PostgreSQL。适合日常开发、本机资料和程序操作，按[本地开发指引](https://docs.teloa.ai/markdown/develop/local-development.md)启动。
- **Docker Compose · 当前可用**：应用、Harness 与数据库均在容器内，适合可选服务器部署和隔离测试。当前从源码构建，步骤见下文。
- **npm 原生安装 · 规划中**：面向个人与 OPC，目标是无需源码即可安装，应用与 Harness 原生运行，默认使用 Docker PostgreSQL。尚未发布。

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

## npm 安装计划

npm 安装将提供现有开源 Web 的安装与启停命令，用户仍在浏览器中工作。计划让 Teloa 和 Harness 原生运行，数据库默认由 Docker 管理，也可选择已有的本机独立 PostgreSQL。已有数据库模式计划沿用本机 `teloa` 专用库限制，不包含任意远程数据库。

安装器目前尚未实现或发布，本文暂不提供 npm 安装命令。当前需本机执行时，请使用[源码运行指引](https://docs.teloa.ai/markdown/develop/local-development.md)。所有方式都需要自行配置模型服务和 API 密钥；原生安装也保留工具授权、工作目录与审批边界，桌面或浏览器操作需要另外接入相应工具。

## 使用 Docker Compose

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

### 开始前

- 安装并启动 [Docker Desktop](https://docs.docker.com/desktop/) 或带 Compose 插件的 [Docker Engine](https://docs.docker.com/engine/install/)。
- 已取得 Teloa 源码，进入含 `compose.yaml` 的目录。当前从源码构建，不提供猜测的官方镜像名。
- 网络能够下载镜像和软件依赖；模型服务与 API 密钥由你自备。

源码获取以 [官网](https://www.teloa.ai/) 正式发布信息为准。尚未取得源码时，通过官网联系渠道确认预览版获取方式。

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

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

### 启动

在源码根目录执行：

```sh
docker compose up -d --build
```

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

### 查看状态

```sh
docker compose ps
```

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

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

### 打开认证链接

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

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

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

### 开始工作

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

[![首次进入 Teloa 时添加 API 密钥或稍后配置的提示](https://docs.teloa.ai/assets/screenshots/model-key.png)](https://docs.teloa.ai/assets/screenshots/model-key.png)

*首次配置提示，尚未填写密钥。这里需要模型服务商的 API 密钥，不是上一步的本机认证链接。*

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

### 停止与继续

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

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