文档

简体中文

English

简体中文

English

切换主题

社区版开源 Web · 0.2.7 发行文档 · 0.2.7内容核对：2026-10-22查看 Markdown

5.1 运行配置与数据位置 ​

当前源码模式让 Teloa 和 DSH 在本机 Node.js 中运行，默认只有 PostgreSQL 使用 Docker；Compose 模式把三者放入容器。两种现有流程都使用标准 Docker，不要求 OrbStack。npm 原生安装另见下文；不要混用不同安装方式的数据目录。

文件与程序在哪里执行 ​

原生模式使用本机工作目录和已接入、已授权的工具；Compose 模式使用容器内的工作目录与程序。默认 Compose 配置没有挂载用户整台电脑的文件系统，也不能直接调用这台电脑上的桌面应用。

需要容器访问电脑上的某个目录时，要自行配置明确的挂载范围与读写权限。挂载路径属于 Docker 引擎所在机器；连接远端引擎不会把客户端电脑的文件自动传过去。详见 Docker 文件挂载说明。

配置分工 ​

配置管理位置注意事项
业务、员工、任务与授权Teloa 对应页面与数据库不通过直接改库绕过校验
模型、密钥、MCP、运行配置设置转入 DSH 配置来源保存后做实际调用验证
扩展组合源码中的组合配置与 setup:dsh修改后需重新准备并构建
浏览器认证启动器生成的当次认证链接重启后变化，不公开保存

Compose 数据位置 ​

持久卷容器路径保存内容
app-data应用 /dataDSH 会话、模型配置、Teloa 工作文件和资料
postgres-data数据库 /var/lib/postgresql/dataPostgreSQL 业务数据
database-secret应用和数据库 /run/teloa-secrets自动生成的数据库口令
credentials-secret仅应用 /run/teloa-credentials（只读）自动生成的密钥存储主密钥，与 app-data 分卷存放

实际卷名带 Compose 项目前缀，例如默认 teloa_app-data。使用 -p 指定其他项目时前缀随之变化，不与源码模式的固定容器混用。

DSH 配置在 /data/dsh，业务运行目录在 /data/teloa，工作目录在 /data/teloa/workspace。数据库只通过 Compose 内网服务 db 访问，不在运行 Teloa 的设备上开放数据库端口。

源码模式数据位置 ​

直接用 Node.js 运行的源码模式下，数据库卷是 teloa-postgres-data；Teloa 运行目录是 .runtime/teloa，DSH 目录为 .runtime/dsh。适配日志在运行目录内的 harness.log，分享前应脱敏。

两种运行方式都需要同时备份数据库和工作文件。仅复制源码或连接配置不是完整备份。

看板只读数据库角色 ​

业务看板的查询以专用数据库角色 teloa_business_reader 直接登录执行。该角色只能读取保存业务对象副本的表和安全函数（二者位于 Teloa 表所在的 schema，默认 public），没有超级用户、建库、建角色、复制或绕过行级安全的属性，也不属于任何其他角色。Teloa 启动时会核对这些条件；不满足时看板查询停用，原因只写入服务端日志。

角色口令随机生成，保存在 Teloa 运行目录中的口令文件（权限 0600，属主为运行 Teloa 的系统用户），数据库只保存 SCRAM 校验值。轮换口令：停止 Teloa，删除该口令文件，再启动 Teloa；启动时会生成新口令并更新数据库角色。不要手工编辑该文件或把它放进备份分享。

npm 安装的数据目录 ​

GitHub Release 已提供 0.2.7 原生包；npm 原生安装见安装指南。安装器将程序版本、应用数据和用户工作目录分开保存：默认 ~/.teloa/releases/ 保存程序，instances/default/ 保存会话与配置，workspaces/default/ 保存工作文件。更新 npm 包不自动迁移数据或重启服务。默认使用 Docker PostgreSQL；已有数据库选项仅接本机专用库。不要将这些目录与现有源码、Compose 安装混用。

密钥与环境变量 ​

模型密钥与连接授权共用 DSH 密钥存储，优先加密保存，主密钥放在系统钥匙串或 DSH 目录之外的主密钥文件中。只有首次初始化且两者都不可用时，自动模式才回退为明文，并在设置页常驻提示；已有加密存储取不到主密钥时锁定，不降级。

  • 源码启动与容器启动会从启动它的环境里剔除像密钥的变量：名字按 _ 分段后含 KEY、TOKEN、SECRET、PASSWORD、AUTH 等整段的，以及值是带口令 URL 的（如 postgres://用户:口令@…）。启动时只打印被剔除的变量名，不打印值。npm 安装的 teloa 本来只传递固定的几个变量。
  • 带口令的代理地址（如 HTTPS_PROXY=http://用户:口令@…）同样会被剔除，且代理变量没有 _FILE 形式；源码与容器启动请改用无需口令的本机代理转发。npm 安装的 teloa 按白名单原样传递代理变量。
  • 模型密钥请在设置页录入；需要从文件注入时，用 <变量名>_FILE 指向一个仅本人可读的文件（例如 DEEPSEEK_API_KEY_FILE）。安全动作令牌同理改用 TELOA_SECURITY_ACTION_TOKEN_FILE。
  • IM 通道密钥（FEISHU_APP_SECRET、FEISHU_ENCRYPT_KEY、LARK_APP_SECRET、LARK_ENCRYPT_KEY、TELEGRAM_BOT_TOKEN、SLACK_BOT_TOKEN、SLACK_APP_TOKEN）只能在 设置 > IM 通道 中保存，环境变量与 _FILE 都不生效；检测到它们被剔除时，启动日志会单独提示一次。
  • 停止 Teloa 后可以维护密钥存储：teloa credentials --action export-plaintext --confirm 在回退到上一版前导出 0600 明文；teloa credentials --action reset --confirm 在主密钥无法恢复时重置，原文件改名为 .bak-<时间> 留存。重置只按登记删除本安装写入钥匙串的条目，不枚举钥匙串；若 macOS 仍弹出钥匙串授权框，拒绝也不影响重置本身。原主密钥的条目会保留，以便日后解开 .bak-*，确认不再需要时可在系统钥匙串里手动删除（服务名 Teloa Credentials）。
  • npm 安装需要联网取得当前平台的系统钥匙串组件。离线安装（npm install --offline）时本机缓存里缺这个组件，或所在平台不受支持，程序仍能装上，但首次初始化会自动改用主密钥文件，且以后不会自动切回系统钥匙串。要改用钥匙串：联网重新安装，停止 Teloa，按需先运行 teloa credentials --action export-plaintext --confirm 留存明文以便重新录入，再运行 teloa credentials --action reset --confirm，然后启动 Teloa（可设 TELOA_CREDENTIALS_STORE=keyring 要求必须使用钥匙串），在设置页重新录入密钥，并在 设置 > 密钥存储 核对当前方式。
  • teloa backup 不含密钥与授权，也不含 DSH 目录下的 .env（它可能含明文密钥）。需要保留时请自行另存到受保护的位置，恢复后放回新安装的 instances/default/dsh/.env（权限 0600）；备份与恢复命令的输出都会提示这一点。
  • 安全相关的 TELOA_* 开关（OAuth 回调地址、安全动作地址与令牌、使用统计与在线市场开关、运行目录、验收开关等）只认启动 Teloa 时继承的进程环境；写在工作区或 DSH 目录的 .env 里不生效。升级注意：以前写在这两个 .env 里的这类变量升级后不再生效，Teloa 启动时会打印一条警告，只列出变量名；请改在启动 Teloa 的环境中设置（npm 安装的 teloa 不传这些变量，OAuth 回调请写在运行目录 config.json 的 oauth.publicCallbackUrl）。
  • AI 工具调用中读取密钥存储文件、主密钥、DSH 目录/.env、数据库口令文件或备份目录的已知形态会被拦截，工具输出与群内回帖里匹配已保存密钥的内容会替换为 [已隐藏]。这是抬高门槛的纵深措施，不覆盖任意编码或所有外发入口，不是安全边界。
  • 设置 > 密钥存储 显示当前的加密方式，存储被锁定或只能明文保存时常驻提示。页面还列出加固前留下的明文密钥副本：旧备份与升级备份目录里的副本，以及启动时隔离的 .credentials.yaml.quarantine-*。只有本人勾选（可逐项或全选）并再次确认后才会删除；删除先原位零覆写再移除。与其他路径共用内容的文件（硬链接）在清单里标明「需手动处理」、不可勾选；链接文件、无法覆写的文件以及列出之后被替换的文件同样不会删除。SSD、APFS 与系统备份（如时间机器）可能仍留有旧数据，零覆写不保证物理擦除。teloa backup --output 指定到别处的备份不在扫描范围内，请自行清理。

技能 API 密钥 ​

技能密钥配置不会自动开放未获支持的资源。X 搜索、财经搜索、宏观数据、CellCog、CellCog 图像生成五个候选仍为 unsupported，不能通过填写密钥启用。

仅当技能已获支持、从市场安装且写明了所需密钥时，才适用以下流程：

  1. 在 资源 > 应用 打开该技能，点 密钥。核对每项密钥的用途、必填状态、目标域名与路径前缀，以及注入位置（Bearer、请求头或查询参数）。不要把密钥发到聊天、写进技能正文或放入环境变量。
  2. 在密码框录入后保存。输入框只写入，不预填或回读已有值，提交后清空；页面只显示「已保存 / 未填写」。第三方 API 密钥由 Teloa 使用上文的加密密钥存储保存，沿用其存储档位与首次初始化回退规则；在 设置 > 密钥存储 核对实际状态。
  3. 若目录中的密钥用途说明发生变化，旧页面的保存会被拒绝，页面刷新说明后须本人重新核对、填写并提交，不自动沿用旧输入。重新确认时，未重新填写的旧密钥会清除。目标、方法、注入位置、变量名、标签或必填状态有任何变化，都要重新核对。
  4. 存储锁定或只读时不能保存、删除，也不将未知状态显示为「未填写」；先到 设置 > 密钥存储 处理。需要移除时，点删除并再次确认，删除该技能已存的全部密钥；这不会在第三方服务商处撤销密钥，撤销须到服务商处理。

调用时由 Teloa 代发：只向技能写明的 HTTPS origin、路径前缀和 HTTP 方法注入密钥，每一跳核对全部 DNS 结果均为公网地址、锁定连接地址并验证目标主机名的 TLS 证书；仅允许仍在技能写明范围内的同源跳转。网页搜索与读取总开关及域名拦截名单仍生效。绑定按当前已安装且生效的市场技能读取，工作区同名技能遮蔽它时不注入；模型无法从密钥接口取得原值，也不会通过环境变量获得这些密钥。

限制： 获准的第三方服务会收到密钥。返回正文按已用密钥值及常见编码形态脱敏，不覆盖任意变形，也无法约束服务商回显或外发，不是通用泄漏边界。技能请求按 DSH 官方代理设置（HTTP_PROXY / HTTPS_PROXY / NO_PROXY）分流：直连时核对公网地址并锁定连接地址；经代理时目标主机由代理解析，锁定地址不成立，实际保护来自目标主机名的 TLS 证书校验。代理地址与账号不会出现在日志、报错或返回内容里。

写入确认与员工授权： 会改动数据的请求（POST、PUT、PATCH、DELETE）每次都会弹确认卡，由本人在工作台决定；IM 上只能拒绝。确认被拒或无人应答后，同一技能对同一地址用同一方法的请求 60 秒内不再出卡。AI 员工的任务会话要使用某个技能的密钥，须由本人在 AI 员工 > 能力 里逐项勾选该技能；以后新增的技能默认不授予，子任务与群聊分派的会话一律不能用。

附加请求头、调用指引与共用密钥： 目录可为技能放开少量附加请求头（最多 8 个），认证类、路由与转发类请求头始终不允许；目录还可附上审查者写的调用说明，它只说明怎么调用，不扩大可访问的地址、方法或请求头。几个技能可以共用一份密钥：密钥页会写明与哪些技能共用，保存或删除对这些技能同时生效。

IM 通道 ​

IM 通道（飞书、Lark（飞书国际版）、Telegram、Slack）随应用内置并默认加载，不需要在市场安装；在 设置 > IM 通道 启用具体渠道后立即运行（不需要重启），需要 Node.js 22 或更高版本。它由本机主动连接平台：Telegram 用长轮询，Slack 用 Socket Mode，飞书与 Lark 用事件长连接（分别连 open.feishu.cn 与 open.larksuite.com），因此不需要公网地址或开放入站端口，但运行 Teloa 的机器要能访问对应平台。

  • 渠道密钥只保存在 DSH 密钥存储里，运行目录下的 im-gateway/ 只存渠道开关、绑定关系与审计记录（目录 0700、文件 0600），不含密钥值与配对码。
  • 飞书开发包不随安装包分发：第一次保存飞书或 Lark 渠道时，Teloa 从 npm 下载锁定的版本、核对完整性并跳过安装脚本，装入运行目录；两者共用这一份。离线环境无法添加飞书或 Lark 渠道。
  • 同一运行目录只允许一个进程连接 IM 渠道（im-gateway/instance.lock）；再启动一个 Teloa 时，它的渠道显示「另一台 Teloa 已连接该渠道」，设置页只读。
  • 启停只改 DSH profile 的组合清单，停用保留 im-gateway/ 与密钥。源码、容器与 npm 升级都会在启动时自动补登记随附扩展并核对其来源必须是本程序目录，无需重跑 pnpm setup:dsh；来源不符时 Teloa 拒绝启动。升级前配过渠道的会自动启用一次（记在 profile 目录的 teloa-官方扩展.json）。
  • teloa backup 不包含密钥：恢复后需要在设置页为渠道重新保存密钥，绑定关系随 im-gateway/ 保留。
  • 迁移时保留 im-gateway/ 中的绑定关系，并在新安装的设置页重新录入密钥；不要直接复制密文文件代替重新录入，主密钥与原安装绑定。

使用方法见在 IM 里和员工对话。

OAuth 连接的回调地址 ​

「应用」页里需要在服务方完成 OAuth 授权的应用连接（如 Supabase 远端、GitLab、Slack）需要把授权结果回调到 Teloa 的 /oauth/callback：

  • 本机部署（Teloa 只监听 127.0.0.1）无需配置，回调地址自动为 http://127.0.0.1:<端口>/oauth/callback。
  • Compose 容器内的 Teloa 固定监听 127.0.0.1:3100，回调与授权入口因此固定为 http://127.0.0.1:3100/oauth/…。把 TELOA_PORT 改成其他端口后，浏览器授权完会回跳到 3100 而到达不了 Teloa：使用 OAuth 连接时请保持 TELOA_PORT=3100，或经 HTTPS 反向代理设置下面的 oauth.publicCallbackUrl，让回调地址与实际访问地址一致。
  • 服务器部署（Teloa 监听 0.0.0.0 等外部地址）必须在运行目录的 config.json 中设置公开的 HTTPS 回调地址，否则发起授权会被拒绝，并提示「服务器部署需在配置文件中设置 oauth.publicCallbackUrl 才能使用 OAuth 授权。」
json
{
  "oauth": {
    "publicCallbackUrl": "https://teloa.example.com/oauth/callback"
  }
}
  • 地址必须是 https://，不能带用户名、口令或 # 片段；反向代理需把该路径原样转发到 Teloa 的 /oauth/callback，并把同目录的 start（如 https://teloa.example.com/oauth/start）转发到 Teloa 的 /oauth/start。授权从这个入口打开：它先给浏览器写入一次性 cookie 再跳转授权服务器，回调必须回到同一浏览器。授权入口链接只回给发起授权的人，请勿转发；链接被先打开的浏览器绑定，其他浏览器无法完成授权。
  • config.json 放在运行目录（源码模式 .runtime/teloa/config.json，Compose 为 /data/teloa/config.json），只能由运行 Teloa 的系统用户拥有且不能对其他用户可写，否则该项被忽略并记一条告警。
  • Teloa 启动时读取一次；修改后需重启。文件中没有该项时，才以环境变量 TELOA_OAUTH_PUBLIC_CALLBACK_URL 兜底。
  • npm 安装的 teloa 命令只向 Teloa 传递固定的几个环境变量，TELOA_OAUTH_PUBLIC_CALLBACK_URL 对它不生效；请写在其运行目录的 config.json（默认 ~/.teloa/instances/default/runtime/config.json）的 oauth.publicCallbackUrl。
  • 授权令牌同样保存在密钥存储里，不再单独写入 mcp/credentials/ 明文文件；加密方式及首次初始化的回退规则见上文。令牌值不进入连接配置、页面或日志。

修改配置后 ​

依次核对保存结果、运行对象和实际调用。修改扩展代码或组合配置后，开发模式可能需要构建并重启；不要把浏览器刷新当成服务已加载新代码。

环境变量清单见命令与配置参考，维护流程见备份、恢复与升级。