1.4 安装与运行 Teloa

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

选择运行方式

本文对应 0.2.12 正式版，已通过 GitHub Release、npm 和 Docker Hub 发布。已有安装升级时保留原安装身份与数据。

• npm 原生安装：无需源码或编译，应用和智能体引擎 DSH 在本机 Node.js 中运行，默认使用 Docker PostgreSQL。按下文安装。
• Docker Hub + Compose：应用、智能体引擎与数据库均在容器内，使用下文的版本配置。正式镜像平台为 Linux ARM64；不提供已验 amd64 的承诺。
• 源码运行：适合开发和修改，按本地开发指引启动。源码根目录仍可执行 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 需先升级。本版实际验收使用 Node.js 24.22.1；安装器声明兼容的其他 Node.js 版本不等于本轮已逐一验收。

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

1. 安装并启动

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

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

可用发行页的 SHA256SUMS 核对下载。也可从 npm 安装同版：npm install --ignore-scripts @teloa/cli@0.2.12。

下文 teloa 指该命令目录中的 node_modules/.bin/teloa。默认安装目录为 ~/.teloa；新安装可通过 --home、--port、--workspace 指定目录和端口。浏览器未自动打开时运行 teloa open。进入后配置模型，再新建项目。

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

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

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

npm install --prefix ./teloa-command-012 --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.12/teloa-cli-0.2.12.tgz
./teloa-command-012/node_modules/.bin/teloa stop
./teloa-command-012/node_modules/.bin/teloa upgrade --to 0.2.12
./teloa-command-012/node_modules/.bin/teloa status

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

2. 环境检查

teloa doctor
teloa doctor --json

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

Linux 受限终端需要可运行的 bubblewrap 或支持 Landlock 的内核；某些 Docker 或模拟环境不具备条件。请修复环境后重跑检查，不要关闭沙箱。诊断通过后仍需配置并测试模型；Web 就绪不等于终端任务或模型已可用。更多情况见故障排查。

3. npm 安装的停止与继续

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

teloa status
teloa stop
teloa up

停止前先处理运行中的工作；使用自定义安装目录时，继续传入原来的 --home。更换版本前先看备份与升级。

使用 Docker Compose

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

开始前

• 安装并启动 Docker Desktop 或装有 Docker Compose 的 Docker Engine。
• 使用 Linux ARM64 环境。下文镜像与配置固定为 teloa/teloa:0.2.12；amd64 尚未验证。
• 网络能够下载镜像和软件依赖；模型由你自行配置，远程服务需要相应 API 密钥。

新建一个目录，下载本版本 Compose 配置。配置沿用密码初始化、独立数据库与持久卷，不需要编译源码。

docker info
docker compose version

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

启动

在新的目录中执行：

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

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

查看状态

docker compose ps

等待 db 与 app 健康。init 是一次性初始化服务，成功退出属于正常行为。持续重启时先检查错误，不要删除数据卷。

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

打开认证链接

docker compose logs --tail=50 app

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

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

开始工作

首次进入时可能会提示添加 API 密钥；可以当场配置，也可以选择“稍后配置”，再进入 设置 > 模型。按模型指南验证一次回应。页面可用和模型可用是两个不同结果。

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

接着完成第一项任务或组建第一支团队。初始环境可能为空，不要求先导入演示数据。

停止与继续

docker compose stop
docker compose start

数据保留在持久卷中。电脑休眠、关机或 Docker 退出后，本机任务和自动化无法继续执行。升级前先备份；修改源码请看本地开发。