安装部署

大约 16 分钟

安装部署

本章汇总 TimechoAgent 0.3.0 的离线安装、配置、启动和连接步骤。以下命令均在目标服务器的 Bash 中执行，本文以本次实操使用的安装目录 /root/timecho-agent-0.3.0-linux-x86_64 为例；如果实际安装目录不同，请将命令中的路径替换为实际目录。示例中的 <...>、/path/to/... 和 example.com 需替换为实际参数。

1. 安装前检查

1.1 确认操作系统和权限

使用具有 root 权限的账号登录服务器：

whoami
cat /etc/os-release

预期具有 root 权限。

1.2 确认 Docker 已安装并运行

docker --version
docker info

本次实测 Docker 版本：

Docker version 28.2.2

如果 Docker 服务未启动：

systemctl enable --now docker

1.3 安装 Docker Compose v2

TimechoAgent 0.3.0 的部署模板要求 Docker Compose v2.20 或更高版本。

先检查当前版本：

docker compose version

Ubuntu 24.04 可使用系统软件包安装：

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y docker-compose-v2
docker compose version

本次实测版本：

Docker Compose version 2.40.3+ds1-0ubuntu1~24.04.1

注意：后续必须使用 docker compose，不要使用旧版 docker-compose。旧版 1.29.x 与当前部署模板不兼容。

1.4 检查磁盘空间和端口

检查磁盘空间：

df -h / /var/lib/docker

本次实测安装前可用空间约 45 GB，安装包约 394 MB，建议至少预留 5 GB 可用空间。

检查 Web 端口是否被占用：

ss -lntp | grep -E ':8080\b'

如果没有输出，说明 8080 端口可用。

本次实测服务器已有 nginx 监听 80 端口，因此 TimechoAgent 使用 8080，未产生端口冲突。如果 8080 已被占用，请在 .env 中修改 HTTP_PORT。

2. 解压和校验安装包

2.1 上传安装包

将以下文件上传到服务器 /root/ 目录：

timecho-agent-0.3.0-linux-x86_64.zip

2.2 解压

cd /root
unzip -q timecho-agent-0.3.0-linux-x86_64.zip

解压后的目录结构应包含：

/root/timecho-agent-0.3.0-linux-x86_64/
├── README.md
├── SHA256SUMS
├── deploy/
│   ├── .env.example
│   └── docker-compose.prod.yml
├── docs/
└── images/
    └── timecho-agent-0.3.0-images.tar.gz

2.3 校验安装包完整性

cd /root/timecho-agent-0.3.0-linux-x86_64
sha256sum -c SHA256SUMS

所有文件均应显示 OK。本次实测结果全部通过。

3. 配置部署环境

3.1 创建 `.env`

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy
cp .env.example .env
chmod 600 .env

如果已经存在 .env，修改前先备份：

cp -a .env ".env.bak-$(date +%Y%m%d-%H%M%S)"

3.2 生成并写入随机密钥

执行以下命令生成 PostgreSQL 口令、应用加密密钥和 JWT 签名密钥：

POSTGRES_PASSWORD="$(openssl rand -hex 24)"
TIMECHO_SECRET_KEY="$(openssl rand -base64 48 | tr -d '\n')"
TIMECHO_JWT_SECRET="$(openssl rand -base64 48 | tr -d '\n')"

sed -i \
  -e "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=${POSTGRES_PASSWORD}|" \
  -e "s|^TIMECHO_SECRET_KEY=.*|TIMECHO_SECRET_KEY=${TIMECHO_SECRET_KEY}|" \
  -e "s|^TIMECHO_JWT_SECRET=.*|TIMECHO_JWT_SECRET=${TIMECHO_JWT_SECRET}|" \
  .env

三项配置的用途：

配置项	用途
`POSTGRES_PASSWORD`	Agent 元数据库连接口令
`TIMECHO_SECRET_KEY`	加密保存模型 API Key、数据库连接口令等敏感配置
`TIMECHO_JWT_SECRET`	登录令牌签名密钥

TIMECHO_SECRET_KEY 一旦丢失，已经加密保存的数据将无法解密，请与 .env 一起妥善备份。

3.3 配置 Context 名称与数据库口令

编辑 .env：

vi .env

至少确认以下配置：

# 监听所有网卡，使用 8080 端口
HTTP_BIND=0.0.0.0
HTTP_PORT=8080

# TimechoDB 默认 Context 名称，不能为空，也不能是 26-dev
TIMECHO_CLI_CTX=timechodb-prod

# TimechoDB 连接口令；此处替换成真实口令，不要保留 CHANGE_ME
TIMECHODB_PASSWORD='真实数据库口令'

# 时区
TZ=Asia/Shanghai

说明：

TIMECHO_CLI_CTX 是 Context 的名称，不是数据库地址。
TIMECHODB_PASSWORD 是 Context 连接 TimechoDB 所用账号的口令。
口令包含 $、#、空格等特殊字符时，应使用单引号包裹。
示例中的 timechodb-prod 必须与配置与验证 TimechoDB Context创建 Context 时使用的名称完全一致。
此处只配置 Context 名称和数据库口令，不会创建数据库实例；TimechoDB 必须已在检查磁盘空间和端口准备完成。
Context 记录必须在配置与验证 TimechoDB Context由管理员通过 timecho-cli 创建或确认，不能通过自然语言创建、修改或删除。

3.4 可选：设置初始管理员口令

如需预先指定初始管理员口令，可在 .env 中设置：

TIMECHO_BOOTSTRAP_ADMIN_PASSWORD='自定义初始口令'

如果留空，系统会在首次启动时随机生成，并写入：

/app/data/initial-admin-password

建议保留默认的空值，让系统随机生成初始口令。

3.5 检查 `.env` 权限

chmod 600 .env
stat -c '%a %U:%G %n' .env

预期输出：

600 root:root .env

4. 导入离线镜像

进入安装包根目录：

cd /root/timecho-agent-0.3.0-linux-x86_64
docker load -i images/timecho-agent-0.3.0-images.tar.gz

本次实测导入的镜像：

timecho-agent-backend:0.3.0
timecho-agent-frontend:0.3.0
postgres:18

检查镜像：

docker image ls | grep -E 'timecho-agent|postgres'

5. 校验 Compose 配置

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy
docker compose config -q

命令无输出且退出码为 0，表示配置校验通过。

如果报错：

Missing mandatory value for "environment" option interpolating ...

通常表示 .env 中仍有必填项为空。重点检查：

grep -nE '^(TIMECHO_CLI_CTX|TIMECHODB_PASSWORD|POSTGRES_PASSWORD|TIMECHO_SECRET_KEY|TIMECHO_JWT_SECRET)=' .env

常见原因：

TIMECHO_CLI_CTX= 为空。
TIMECHODB_PASSWORD= 为空。
使用的是旧版 docker-compose。
当前目录不是 deploy 目录，Compose 没有读取到正确的 .env。

Compose 通常只首先报告第一个空变量，修正后应再次执行 docker compose config -q，确认其余必填项也没有遗漏。

6. 启动服务

6.1 启动

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy
docker compose up -d

首次启动会依次完成：

创建 Docker 网络和数据卷。
启动 PostgreSQL 并等待健康检查通过。
启动后端并执行数据库迁移、初始化管理员。
等待后端健康后启动前端。

6.2 查看状态

docker compose ps

预期三个服务均为 Up 且状态为 healthy：

timecho-agent-prod-postgres-1    Up ... (healthy)
timecho-agent-prod-backend-1     Up ... (healthy)
timecho-agent-prod-frontend-1    Up ... (healthy)

本次实测约 17 秒后端变为健康，前端随后启动。

查看日志：

docker compose logs --tail=200 backend
docker compose logs --tail=100 frontend

持续观察后端日志：

docker compose logs -f backend

7. 验证安装结果

7.1 本机 API 验证

curl -fsS http://127.0.0.1:8080/api/v1/system/info

本次实测返回内容中的关键字段：

{
  "code": "OK",
  "data": {
    "name": "TimechoAgent",
    "version": "0.3.0",
    "demoMode": false
  }
}

7.2 服务器 IP 验证

curl -fsS http://<TimechoAgent_IP>:8080/api/v1/system/info

能够正常返回 JSON，说明监听地址和端口配置正确。

7.3 浏览器访问

打开：

http://<TimechoAgent_IP>:8080/

8. 首次登录

8.1 查找初始管理员口令

首次登录所需信息如下：

项目	位置或值
Web 登录地址	`http://<TimechoAgent_IP>:8080/`
管理员用户名	`admin`
默认初始口令位置	后端容器内的 `/app/data/initial-admin-password`
自定义初始口令	如果 `.env` 中设置了 `TIMECHO_BOOTSTRAP_ADMIN_PASSWORD`，则以该配置值为准

默认初始口令文件位于 backend 容器内部，不是 deploy/.env，在宿主机 deploy 目录下无法直接看到。进入部署目录后执行以下命令查询：

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy
docker compose exec backend cat /app/data/initial-admin-password

如果 .env 中设置了 TIMECHO_BOOTSTRAP_ADMIN_PASSWORD，系统不会再生成随机初始口令，此时应使用 .env 中配置的值登录。

初始口令只能用于首次登录。请勿通过截图、聊天工具或公共文档传播该口令。

8.2 登录并修改口令

使用用户名 admin 和查找初始管理员口令查到的初始口令登录 Web 控制台。

首次登录后必须修改口令。新口令应满足：

至少 8 位；
至少包含大写字母、小写字母、数字、符号中的 3 类；
不能与用户名相同，也不能是用户名倒序。

修改完成后，先退出并使用新口令重新登录，确认新口令生效。

8.3 建议删除初始口令文件

确认新口令可以正常登录后，建议立即删除后端容器中的初始口令文件，避免后续被误用：

docker compose exec backend rm /app/data/initial-admin-password

验证文件已经删除：

docker compose exec backend sh -lc 'test ! -e /app/data/initial-admin-password && echo "初始口令文件已删除"'

8.4 配置通用大模型（必须）

TimechoAgent 的智能体对话和自然语言数据库操作依赖已配置的大模型服务。首次登录并修改管理员口令后，必须先配置至少一个可用的大模型并通过连通性测试；未完成前不应继续配置或使用数据库连接，也不应执行受审批的数据操作。模型配置不是可选项，而是登录后使用 Agent 功能的前置条件。

配置步骤：

使用管理员账号登录 Web 控制台。
打开左侧“模型配置”，进入“新增配置”。
接入方式选择“OpenAI 兼容接口”，或选择与实际服务匹配的接入方式。
填写配置名称、Base URL、API Key、模型名和上下文窗口。
用于数据库操作时，必须启用“工具调用”；需要分析图片时再启用“读图”。
先执行“连通性测试”，确认返回连通正常后保存。
将该模型设为所用智能体的默认模型，并在“智能体”页面确认默认模型设置。

大模型服务必须能从 TimechoAgent 服务器访问，而不是只从浏览器所在电脑可访问。API Key 由 TimechoAgent 加密保存；不要把真实 API Key 写入本手册或通过公共聊天工具传播。

保存后进入“对话工作台”，选择已绑定默认模型的智能体并发送一条普通问题。例如：

请回复“模型连接正常”，不要执行任何数据库操作。

如果能够正常返回，说明模型接入完成。后续可以在对话工作台中使用管理员已经配置好的 Context 进行查询和数据操作；涉及写操作时按页面提示审批。Context 的新增、修改、删除和切换不能通过自然语言完成。

9. 配置与验证 TimechoDB Context

安全边界：TimechoAgent 不能安装 TimechoDB 服务实例，也不能通过自然语言新增、修改、删除或切换 TimechoDB Context。Context 的连接地址、账号、口令、方言和 TLS 等配置，必须由管理员在服务器上使用 timecho-cli 完成；Agent 只能使用已经配置好的 Context 进行自然语言交互。

TimechoDB Context 是 TimechoAgent 访问现有 TimechoDB 的连接配置，不会创建 TimechoDB 服务实例，也不会创建数据库账号。Context 的生命周期管理属于管理员运维操作，不属于自然语言对话能力。Context 的 CLI 配置与 Web 端模型配置相互独立；在对话工作台中使用数据库连接前，两项配置都必须完成。

管理员需要在 Agent 之外完成以下配置：

操作	推荐入口	说明
创建 Context	服务器 `deploy` 目录下的 `timecho-cli`	配置主机、端口、账号、方言和 TLS 等连接参数
修改 Context	`timecho-cli ctx update`	仅修改明确指定的连接参数
删除 Context	`timecho-cli ctx remove`	高风险操作，执行前必须确认影响范围
验证 Context	`timecho-cli ctx list/show` 和 SQL 连接测试	确认配置和网络连通性
使用 Context	Web 对话工作台	只使用既有连接，不改变 Context 配置

当前版本不提供“通过自然语言创建或修改 Context”的等效方式。这是 TimechoAgent 基于安全考虑设置的能力限制，不应尝试通过提示词绕过。

9.1 准备连接信息

以下信息必须来自已经存在且可访问的 TimechoDB 实例。表中的地址和账号仅为占位示例，正式部署时应全部替换：

参数	示例	说明
Context 名称	`timechodb-prod`	应与 `.env` 中 `TIMECHO_CLI_CTX` 一致
数据库地址	`<TimechoDB_IP或域名>`	已部署的 TimechoDB 服务器地址，不是示例 IP
端口	`6667`	默认端口
数据库用户	`<数据库用户名>`	已创建的专用账号，建议使用最小权限
数据库口令	`<真实口令>`	对应 `.env` 中的 `TIMECHODB_PASSWORD`
方言	`tree` 或 `table`	必须与实际数据模型一致
默认数据库	`iotdb`	`table` 模式按需填写

9.2 创建 Context（管理员 CLI）

以下命令均在 deploy 目录执行。根据实际数据模型选择 Tree 或 Table 其中一种。

Tree 模型：

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy

docker compose exec backend timecho-cli ctx add timechodb-prod \
  --host '<TimechoDB_IP或域名>' \
  --port 6667 \
  --user '<数据库用户名>' \
  --dialect tree \
  --json --non-interactive

Table 模型：

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy

docker compose exec backend timecho-cli ctx add timechodb-prod \
  --host '<TimechoDB_IP或域名>' \
  --port 6667 \
  --user '<数据库用户名>' \
  --dialect table \
  --database iotdb \
  --json --non-interactive

重要限制：

不要通过 Web 对话要求 Agent 创建或修改 Context，当前版本会按安全策略拒绝。
不要添加 --password-stdin。CLI 会从后端容器的 TIMECHODB_PASSWORD 环境变量读取口令。
不要添加 -u root。Context 配置必须由镜像默认用户写入共享卷。
table 模型必须显式指定 --dialect table，并提供已存在的默认数据库。
需要 TLS 时，应另行挂载 CA、客户端证书和私钥，再使用 --tls、--ca、--cert、--key 等参数。
不要重复创建同名 Context；如果同名 Context 已存在，应先查看其配置。

9.3 修改 Context（管理员 CLI）

修改前先确认现有配置：

docker compose exec backend timecho-cli ctx list --json --non-interactive
docker compose exec backend timecho-cli ctx show timechodb-prod --json --non-interactive

例如，管理员需要变更数据库地址和端口时执行：

docker compose exec backend timecho-cli ctx update timechodb-prod \
  --host '<新的TimechoDB_IP或域名>' \
  --port 6667 \
  --json --non-interactive

变更方言或默认数据库时，必须与目标数据库的实际数据模型一致：

docker compose exec backend timecho-cli ctx update timechodb-prod \
  --dialect table \
  --database iotdb \
  --json --non-interactive

注意事项：

ctx update 只修改明确指定的参数；执行前先用 ctx show 记录原配置。
数据库口令和 TLS 凭据属于受控配置，不应通过聊天内容、命令参数或日志传递。
凭据轮换应先更新 .env 中对应的受控配置，再按 timecho-cli ctx update --help 的当前参数完成更新和验证。
删除 Context 属于高风险操作。确需删除时先确认没有用户或智能体正在使用，再执行 ctx remove；不要通过自然语言删除。
管理员完成变更后，应通知使用者重新验证连接，避免继续使用旧地址或旧凭据。

9.4 验证 Context

无论创建还是修改，都应在服务器上执行以下验证：

docker compose exec backend timecho-cli ctx list --json --non-interactive
docker compose exec backend timecho-cli ctx show timechodb-prod --json --non-interactive

执行连接测试：

docker compose exec backend timecho-cli sql "SHOW DATABASES" \
  --ctx timechodb-prod \
  --json --non-interactive

如果能够返回数据库列表，说明 Context 和 TimechoDB 连接正常。完成验证后，再登录 Web 对话工作台使用该 Context。

9.5 绑定用户

使用 admin 登录 Web 控制台。
进入“用户管理”。
新建或编辑用户。
在“数据库 Context”中选择或填写 timechodb-prod。
保存配置。

此步骤只把已存在的 Context 分配给用户，不会创建或修改数据库连接配置。Context 本身的变更仍必须由管理员使用 timecho-cli 完成。

生产环境建议：

为 Agent 单独创建数据库账号。
不要直接使用数据库 root 账号。
按业务库授予最小权限。
不允许普通用户绕过审批执行高风险写操作。

10. 服务启停命令

本节用于安装完成后进行服务启停和快速查看。日常巡检、资源检查和故障处理见日常运维。

以下命令均在 deploy 目录执行：

cd /opt/timecho-agent/deploy

查看运行状态：

docker compose ps

查看后端日志：

docker compose logs --tail=200 backend

持续观察日志：

docker compose logs -f backend

重启所有服务：

docker compose restart

停止服务：

docker compose stop

再次启动：

docker compose start

停止并删除容器和网络，但保留数据卷：

docker compose down

禁止执行 docker compose down -v，除非明确要删除 PostgreSQL、Agent 数据和 CLI Context 配置。

11. 故障排查

11.1 报错：`Missing mandatory value for "environment" option`

原因：.env 中必填变量为空。

处理：

grep -nE '^(TIMECHO_CLI_CTX|TIMECHODB_PASSWORD|POSTGRES_PASSWORD|TIMECHO_SECRET_KEY|TIMECHO_JWT_SECRET)=' .env

补齐后重新执行：

docker compose config -q

11.2 报错：`docker: unknown command: compose`

原因：只安装了旧版 docker-compose，没有安装 Compose v2。

处理：

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y docker-compose-v2
docker compose version

11.3 后端启动失败

查看日志：

docker compose logs --tail=300 backend

常见原因：

PostgreSQL 口令不一致；
TIMECHO_SECRET_KEY 少于 32 字节；
TIMECHO_JWT_SECRET 为空；
TIMECHO_CLI_CTX 等于 26-dev；
管理员初始口令弱于安全策略；
PostgreSQL 服务未健康。

11.4 前端没有启动

前端依赖后端健康检查。先确认后端：

docker compose ps
docker compose logs --tail=200 backend

后端恢复健康后，前端会自动启动。

11.5 已登录但无法自然语言对话

如果能够登录 Web 控制台，但对话工作台不能正常工作，依次检查：

是否已按配置通用大模型（必须）配置通用大模型并通过连通性测试；
智能体是否已设置默认模型；
是否已由管理员通过 timecho-cli 配置并验证 Context；
模型是否支持“工具调用”，Base URL 是否能从 Agent 服务器访问；
“执行通道”是否显示正常；
后端日志中是否有模型鉴权、超时或网络错误。

cd /root/timecho-agent-0.3.0-linux-x86_64/deploy
docker compose logs --tail=200 backend

11.6 Context 连接失败

检查：

docker compose exec backend timecho-cli ctx list --json --non-interactive
docker compose exec backend timecho-cli sql "SHOW DATABASES" --ctx timechodb-prod --json --non-interactive

重点核对：

TimechoDB 地址和端口是否可访问；
账号和 TIMECHODB_PASSWORD 是否正确；
tree / table 方言是否正确；
table 模式的默认数据库是否存在；
容器内是否能解析并访问数据库主机；
数据库是否启用了 TLS 白名单或 IP 限制。

11.7 自然语言无法创建或修改 Context

这是当前版本的预期行为，不是安装故障。TimechoAgent 基于安全考虑，将数据库实例安装和 Context 生命周期管理保留在自然语言能力边界之外。

处理方式：

由管理员在服务器 deploy 目录使用 timecho-cli ctx add/update/remove 完成配置。
使用 ctx list/show 和 SHOW DATABASES 验证连接。
重新登录 Web 对话工作台，使用已经配置好的 Context 进行自然语言交互。
不要在对话中尝试通过提示词要求 Agent 绕过限制。