文档

简体中文

English

简体中文

English

切换主题

社区版开源 Web · 0.2.27 发行文档 · 0.2.27内容核对：2026-11-05查看 Markdown

1.4 安装与运行 Teloa ​

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

选择运行方式 ​

本文对应 0.2.27 正式版，已通过 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，不连接任意远程数据库。

先确认运行平台

本版原生安装已验收 macOS ARM64（Apple 芯片，Darwin 25）；随包维护工具仅接受 darwin、arm64 和 Darwin 主版本 25。其他 macOS 主版本不满足当前工具的平台校验，不能据此视为已支持。Windows 原生暂不支持，其他原生平台未纳入本版验收。Docker 镜像的运行平台为 Linux ARM64，不是任意架构的 Linux 或 Windows 原生环境。

macOS 原生备份及升级前自动备份中，单个文件达到 16 MiB 时必须通过上述维护工具，在同一 APFS 卷上克隆备份；源和备份目录不能跨卷。平台校验或克隆失败会停止备份，不会回退普通复制。安装前请确认系统版本及备份位置；日后升级也依赖此备份条件。

最低支持 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.27 的安装命令；先运行 up 初始化，再核对运行状态：

sh
npm install --prefix ./teloa-command --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.27/teloa-cli-0.2.27.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.27。

下文 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.27 命令包先停止，再运行 teloa upgrade --to 0.2.27；升级会自动备份并核对候选就绪，不要覆盖程序目录或重新初始化原数据库。升级会核对原安装身份与数据，不能通过新建空库代替迁移。

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

sh
npm install --prefix ./teloa-command-027 --ignore-scripts https://github.com/teloa-ai/teloa/releases/download/v0.2.27/teloa-cli-0.2.27.tgz
./teloa-command-027/node_modules/.bin/teloa stop
./teloa-command-027/node_modules/.bin/teloa upgrade --to 0.2.27
./teloa-command-027/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 或模拟环境不具备条件。请修复环境后重跑检查，不要关闭沙箱。诊断通过后仍需配置并测试模型；Web 就绪不等于终端任务或模型已可用。更多情况见故障排查。

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

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

sh
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.27；amd64 尚未验证。
  • 网络能够下载镜像和软件依赖；模型由你自行配置，远程服务需要相应 API 密钥。

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

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.27/compose.yaml --output compose.yaml &&
curl --fail --location https://docs.teloa.ai/downloads/0.2.27/prepare-fresh-install.sh --output prepare-fresh-install.sh &&
sh ./prepare-fresh-install.sh &&
docker compose pull &&
docker compose up -d --no-build

后续命令都在刚创建的 teloa-free 目录中执行。新安装准备脚本先检查已有容器、数据卷与网络，再将独立项目名保存到 .env；不创建容器或修改旧数据。目录已有 .env、项目被占用或 Docker 检查失败时停止，不继续启动。配置未设置项目名时也会拒绝启动。

已有安装请走备份与升级，保留原项目名和 .env，不要重跑准备脚本或通过新建目录替代升级。准备完成后也不要重新生成项目名，避免接入另一组空数据卷。

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

查看状态 ​

sh
docker compose ps

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

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

打开认证链接 ​

sh
docker compose logs --tail=50 app

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

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

开始工作 ​

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

未配置聊天模型时的模型选择器。需要先到设置中保存自己的模型凭据。

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

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

停止与继续 ​

sh
docker compose stop
docker compose start

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