TimechoAgent 使用手册

大约 64 分钟

TimechoAgent 使用手册

1. 产品介绍

1.1 简介

TimechoAgent 是面向 TimechoDB 的数据库智能助手。用户可以在浏览器中用日常语言描述需求，由助手查询数据、执行经授权的数据库操作，并解释结果。

从查询设备指标，到生成图表、整理运维报告，再到阅读操作规范，用户可以在同一会话中持续提问和补充资料。涉及写入或删除数据时，平台会按规则请求审批，并保留操作记录，便于后续核查。

1.2 核心能力

自然语言操作数据库：描述要查询或处理的数据，助手生成相应数据库指令，在账号权限和审批规则允许的范围内执行。
数据分析与成果输出：汇总和比较数据，展示折线图或柱状图，将查询结果导出为 CSV，或根据已查询数据生成 Markdown 报告。
资料阅读与知识辅助：读取文档附件，结合知识库中的规范回答并注明出处；使用支持读图的模型时，可以识别图片和扫描件。
会话与工作成果管理：围绕同一任务持续追问，保存个人偏好，将 SQL、脚本或草稿写入会话工作区，继续修改并下载。工作区文件只保存，不会自动执行。
权限、审批与审计：按角色分配管理和审批权限，为用户绑定数据库连接，记录执行结果、审批和用量，供授权人员核查。
预测与外部工具扩展：管理员完成配置后，可调用 TimechoAI 进行时间序列预测，或通过外部工具连接其他服务；相关数据发送需按平台规则审批。

1.3 适用场景

场景	示例需求	可以获得的结果
日常数据查询	“查昨天各台设备的平均温度，列出最高的 5 台。”	查询结果及统计说明，可继续要求图表或导出
运维状态检查	“检查数据库节点和磁盘状态，列出需要关注的问题。”	状态检查结果及明细，供运维人员进一步判断
运维报告整理	“根据本次已经查询的数据生成运维日报，注明统计范围。”	可复制或下载的 Markdown 报告
操作规范查阅	“按知识库中的设备规范，说明温度超限后的检查步骤。”	带文档名、页码或章节等出处的回答
脚本和草稿整理	“把本次巡检 SQL 保存到工作区，后续再改成按小时统计。”	可继续修改、复制或下载的文本文件
趋势预测	“预测某台设备接下来一小时的温度。”	审批后得到预测值与历史、预测曲线；需已配置预测服务且数据符合要求

查询和操作范围取决于账号绑定的数据库权限。使用报告或执行数据库变更前，应结合实际业务核对结果；具体操作步骤和限制见后续章节。

区域	常用入口和用途
左侧「工作台」	「对话工作台」用于提问；「会话管理」用于重命名、摘要和回收站操作
左侧「知识与记忆」	「知识库」查看可用资料；「记忆」管理个人偏好
左侧「治理与审计」	「用量统计」查看用量；授权管理员还可进入「审计中心」
左侧「系统管理」	平台管理员配置智能体、技能、模型、外部工具和用户；「执行通道」平台管理员与数据库管理员可见
对话区域	输入问题、上传资料、查看回答、查询结果、图表和审批卡
对话页右侧	查看「上下文预览」「执行通道」「工作区」；审批人员还可查看待审批操作
右上角用户菜单	「修改密码」「API Token」「关于」「退出登录」

1.5 建议阅读顺序

如果管理员已经给你网址和账号，可直接从第 2 章开始，不需要先阅读安装命令。

你的角色或任务	建议阅读顺序
普通用户（USER）：提问、分析数据和管理自己的会话	第 2 章「快速入门」→ 第 3 章「常用功能」→ 第 4 章「操作审批」
数据库管理员（DB_ADMIN）：处理授权范围内的审批、核查操作	先了解第 2、4 章，再阅读第 5 章「数据库管理员：审批与审计」
平台管理员（ADMIN）：配置账号、模型、助手和资料	第 6 章「平台管理员：让用户能够正常使用」；需要审批时再读第 4、5 章
部署与运维人员：安装和维护服务	第 7 章「安装部署」→ 第 8 章「日常运维」→ 第 9 章「备份、恢复与升级」；特殊配置按需查附录 A–C
脚本或系统接入人员	第 10 章「API Token 与接口接入」；涉及数据库操作时同时阅读第 4 章
遇到提示或需要帮助	第 11 章「常见问题与支持」

2. 快速入门

开始前，准备好管理员提供的平台网址和账号，并确认账号已绑定所需数据连接。

2.1 登录

打开管理员提供的平台网址。
在「用户名」和「密码」中输入分配的账号及初始密码。
点击「登录」。
首次登录被要求改密时，按提示修改密码。默认至少 8 位，包含大写字母、小写字母、数字、符号中的至少 3 类，不能与用户名或其倒序相同。

注意：忘记密码或账号被锁定时，联系管理员。默认连续输错 5 次会锁定 15 分钟。

成功的标志：进入系统首页；若先进入修改密码页面，完成改密后再开始使用。

2.2 发起第一次提问

打开「对话工作台」，点击「新建会话」。
选择助手，通常为「TimechoDB 运维助手」。
输入一个简单问题，例如：
```
我当前可以查看哪些数据库？
```
按 Enter 发送；Shift+Enter 可以换行。
等待回答，查看查询结果和说明。

成功的标志：助手实际完成查询，并展示结果。如果只是解释操作方法，尚不能据此判断数据已经查到或修改完成。

2.3 怎样提问更容易得到准确结果

尽量说明“查什么、查哪段时间、怎样整理”。不清楚表名或字段时，可以先让助手帮你查看。

例如：

我想看昨天各台设备的平均温度。先确认数据表和温度字段，再查询；缺失数据不要当作 0，结果按设备整理。

时间要求严格时，写明日期和时区，例如“2026-10-12 当天，按北京时间统计”。

2.4 管理自己的账号

你想做什么	入口与说明
修改密码	右上角用户菜单 →「修改密码」；改密后，其他浏览器需重新登录
退出登录	右上角用户菜单 →「退出登录」；公用电脑使用完毕后务必退出
查看版本	右上角用户菜单 →「关于」；反馈问题时提供版本号
创建脚本接入凭据	右上角用户菜单 →「API Token」；具体操作见第 10 章

登录有效期：默认 8 小时。同一浏览器的多个标签页共用登录状态；在一个标签页退出或换账号后，其他标签页会随之更新。

2.5 了解常用概念

智能体（Agent）：按用途配置的助手，例如「TimechoDB 运维助手」。新建会话时选择合适的助手即可，普通用户通常无需配置它。
会话：保存一次讨论中的问题、回答、查询结果和审批记录。围绕同一任务可以继续追问；换一个任务时，建议新建会话。
数据连接（Context）：一套数据库连接和账号配置。管理员为你的平台账号绑定后，你就使用其中的数据库账号执行操作；创建平台账号不会自动创建数据库账号。

3. 常用功能

提问、上传资料或查询时，相关问题、会话内容、资料和查询结果可能发送给管理员配置的模型服务。请只使用本单位允许提交给该服务的数据，不提供密码或 API Key。

3.1 查询和分析数据

直接描述问题，例如：

找出昨天平均温度最高的 5 台设备，说明统计时间和温度单位。

查看结果时注意时间范围、对象和单位。出现“结果已截断”，说明页面只展示了一部分；需要完整统计时，让助手先汇总，再回答：

请统计全部符合条件的数据，不要只根据当前展示的几行得出结论。

3.3 生成报告

先完成所需查询，再提出：

根据本次已经查到的数据生成运维日报，包含统计范围、主要指标、异常情况和建议；没有数据支持的项目请标为待确认。

获取报告：在交付物卡片中点击「复制 Markdown」或「下载 .md」。Markdown 是一种文本格式，也可以用文本编辑器打开。

使用前核对：检查报告结论与实际查询结果是否一致。

3.4 按知识库中的规范回答

知识库是管理员上传的操作规范、说明文档等资料。你可以说：

按设备操作规范解释温度超限后的检查步骤，注明文档名称和章节。

查看出处：回答应附文档名、页码或章节。需要更多上下文时，可以继续说“请查看这段内容前后的说明，再解释”。平台由管理员将对话引擎配置为按问题自动检索时，每轮会先自动检索一次知识库，命中的出处显示在过程信息的「知识库检索」里；管理员也可关闭这项自动检索，此时按需在问题中点名知识库。

找不到资料时：

尝试文档中的完整关键词；英文尽量使用完整词，例如 temperature，缩写 temp 不一定能命中。带下划线的名字会拆开检索，例如搜 iot 也能命中 demo_iot。
仍找不到时，联系管理员检查文档状态和助手的知识库设置。

3.5 导出查询结果

查询后继续说“把这些结果导出成 CSV”。导出是只读操作，不需要审批。
在下载卡片中核对文件名、行数、大小和列信息，再下载文件。

导出限制：单个文件默认最多 10 万行、50 MB；超出时只保留前面的内容并标记“已截断”。以 =、+、-、@ 开头的文字（纯数字除外）会自动在前面补一个单引号，避免在表格软件中被当作公式执行。

访问与清理：文件只有当前会话用户可以下载，会话彻底删除时一并清理。

3.6 查看数据库状态

可以提问“数据库现在状态怎么样”或“哪个节点有问题”。助手会检查连接、版本、激活、节点、分区、同步任务、正在执行的查询、系统变量和磁盘等状态，并逐项给出结果。这是只读检查，不需要审批。

3.7 预测

开始前确认

已配置 Timecho AI 密钥，并为当前智能体启用预测工具；未配置时请联系平台管理员。
使用单条时间序列；多台设备的数据应先按设备筛选。
数据按时间升序、大致等间隔，且至少有 16 行。
默认最多发送最后 2000 行，预测步数为 1～720。

发起预测

提问，例如“预测某台设备接下来一小时的温度”。
核对审批卡中的列、行数和目标服务，确认后批准。
查看预测值表格和“历史 + 预测”曲线。

数据发送与审批：预测会把查询得到的时间列和目标列发送到配置的 Timecho AI 服务，因此即使是只读查询，也会先显示审批卡；每次发送会记录到审计中心的“数据出域”。勾选「本会话内同类操作自动放行」后，同一会话的后续预测可不再逐次弹卡。

3.8 使用文档和扫描件

上传并提问

在输入框下方点击「文档」，或直接把文件拖入输入框。
等待上传与解析完成，检查附件条上的文件名、字数和页数。
输入需求，例如“总结这份说明中的日常检查步骤，并注明页码”，再发送。
核对回答的文档名称和页码；长文档可要求助手继续读取后续部分。

未发送的附件可以点 × 移除；切换会话时，未发送的附件会被丢弃。

文件格式与限制

项目	默认要求
文件格式	PDF、Word（.docx）、TXT、Markdown、CSV；旧版 Word .doc 需先另存为 .docx
单文件大小	不超过 20 MB
数量	一条消息最多带 5 个文档，同一会话最多保留 20 个
文档文字	每个文档最多保留 50 万字，超出部分截断并标明
总上传大小	还受总请求大小限制；失败时分批或拆分后再试

CSV 入库说明：对话里上传 CSV 用于读取和分析文件，不等于将数据写入数据库。需要批量入库时，先由数据库管理员确认导入方案；需要进一步操作支持时，请联系天谋团队。

扫描件如何处理

模型要求：没有文字层的 PDF 需要支持读图的会话模型逐页识别。不支持时，选择支持读图的模型新建会话，再上传。
等待识别：附件条显示「读图识别中」时，等完成后再发送。
页数与用量：默认最多识别前 20 页，超出部分不会自动读取；每页识别会消耗模型用量。
识别中断：服务重启中断识别时，需要重新上传。
混合 PDF：文字与扫描页混合的文件可能漏掉扫描页内容，请将需要识别的扫描页单独整理后上传。

3.9 使用工作区

可以说“把本次巡检 SQL 保存为工作区中的巡检.sql”，再继续说“把巡检.sql 改成按小时统计”。

在对话页右侧「工作区」查看文件列表，点击「查看」可阅读内容、复制或下载，点击「删除」可清理不再需要的文件。

保存后不会自动执行：工作区只保存文本，保存脚本不代表脚本已运行。

访问与清理：文件只有本人可见，会话彻底删除时一并清理。
容量限制：单个文件默认不超过 512 KB，每个会话最多 100 个文件、合计 5 MB。
空间不足：先下载需要保留的文件，再删除旧文件。

3.10 使用图片

可以将图片粘贴或拖入输入框，请助手识别。所选模型必须支持读图，不支持时按界面提示切换。

上传前去掉密码、客户身份信息和其他敏感内容。 图片只对上传者可见；会话彻底删除时，图片也会一并清理。仍不要上传不应提交给模型服务的高敏感图片。

3.11 保存偏好

在「记忆」中添加个人偏好，例如“默认按北京时间解释日期”，也可以从会话提取记忆。记忆用于后续回答，发现内容错误或过时时应及时修改。

不要在记忆中保存密码、API Key 或其他秘密。

3.12 管理会话和停止回答

你想做什么	怎么操作
继续讨论	打开原会话，继续提问
修改标题	在「会话管理」重命名
对话太长	在「会话管理」生成摘要，或新建会话
停止本轮	点击「停止生成」
删除历史	在「会话管理」删除；重要报告先下载

继续或停止回答：关闭或刷新页面不会自动停止回答，重新打开后可以继续查看。会话较长时，系统可能在新一轮开始前自动压缩较早内容，最近几轮会保留原文。

删除后会发生什么：

会话先进入回收站，默认保留 30 天；保留期间可以恢复或彻底删除。
到期后会连同消息、图片、文档、工作区文件和导出文件一起清理。
审批、审计和用量记录不会随会话删除。

注意：删除会话或停止回答不会撤销已经提交的数据库操作。

3.13 查看用量

在「用量统计」查看自己的使用情况和当日预算。“token”是模型用量的计数单位。

预算用完：联系管理员调整，或等次日恢复。

费用口径：标为“估算”的部分不是供应商的准确计费数据；预算也不是严格费用封顶。

4. 操作审批

4.1 为什么有时需要审批

读取数据与修改数据的影响不同。系统按四类处理：

操作	例子	通常怎样处理
只读（READ）	查询数据、查看表结构	默认自动执行
一般写入（WRITE）	建表、插入数据、修改结构	审批后执行，可按会话策略放行
危险操作（DANGER）	删除数据、删除表	每次审批，并输入确认词
禁止操作（FORBIDDEN）	授权、关闭数据库、多条语句拼接等	直接拒绝，不能通过审批放行

具体等级以系统对完整操作的判断为准。“SQL”是数据库操作指令，通常由助手生成，你会在审批卡中看到。

4.2 看到审批卡时怎么做

看清目标数据库、对象和操作内容。
不理解影响时，先请数据库管理员确认。
确认符合授权后，点击「批准执行」；不合理则「拒绝执行」，可填写原因。
查看最终执行结果，批准成功不等于数据库执行成功。

谁来批准：

情况	审批要求
一般写入	普通用户可批准自己会话中的操作
危险操作	由授权数据库管理员或平台管理员批准
已启用四眼审批的写操作	必须由发起人以外的授权人员批准，发起人只能撤回

能否自动放行：

勾选「本会话内同类操作自动放行」会减少同类写入的审批，使用前确认范围；它不会放行危险操作。
平台禁止会话自动放行写操作时，相关开关不会出现，一般写入也需逐次审批。
启用四眼审批时，相关写操作不能记住或自动放行。具体规则以审批卡显示为准。

注意：被拒绝后不要换会话或改写指令绕过审批。组织另有变更审批要求时，仍须遵守。

4.3 预测和外部工具的审批

发送内容：预测会发送查询结果的时间列和目标列；外部工具会发送调用参数。即使会话允许自动执行只读查询，这些操作通常仍需要审批。
批准前核对：检查发送内容、目标服务和业务授权。
会话自动放行：勾选「本会话内同类操作自动放行」后，同一会话的后续预测或同一个外部工具调用可不再逐次弹卡；危险数据库操作始终逐次审批。
执行后核查：「数据出域」记录用于核查发往平台外的调用；审批通过后还需检查结果，不能把授权成功当作执行成功。错误提示的处理见第 11.1 节。

5. 数据库管理员：审批与审计

5.1 处理待审批操作

登录后，在「对话工作台」右侧查看「待审批（全部会话）」。

核对发起问题、SQL、目标数据连接和剩余时间。
确认操作对象、影响范围以及组织要求的备份/变更授权。
危险操作按卡片输入确认词，例如 DROP，再批准。
不同意则拒绝并说明原因。
检查执行状态，必要时通过只读查询核对结果。

审批时效：默认等待 10 分钟；超时、用户停止、删除会话或服务重启后，旧审批不能继续执行。
信息范围：全局审批会展示必要信息，不授予查看别人完整会话的权限。
四眼审批：自己发起的操作需要另一位授权审批人处理。
处理提醒：目前没有邮件或即时消息审批通知，请留意待审批面板，并与发起人约定处理时间。

5.2 查询和导出审计

打开「审计中心」，选择「执行审计」或「审批记录」。
按时间、用户、风险等级、状态、数据连接或 SQL 关键字筛选。
核查“谁发起、谁批准、在哪个数据连接执行、执行是否成功”。
需要保存时，按当前筛选条件导出 CSV，可用 Excel 打开。

时间范围：默认查询最近 7 天，单次时间跨度最长 366 天；默认审计保留 180 天。

保存要求：导出文件含用户及操作信息，应受控保存。

6. 平台管理员：让用户能够正常使用

6.1 首次配置顺序

完成管理员改密后，按以下顺序配置：

配置真实模型并做连通性测试。
为「TimechoDB 运维助手」选择该模型。
在「执行通道」确认运维建立的数据库连接可用；需要时为每个连接单独设置口令。
创建用户并绑定数据库连接，按需设置预算和用户组。
上传知识库、绑定技能，并设置智能体和知识库的可用范围。
用普通用户账号试一次只读查询；在独立测试对象上验证审批。

同时建立第二个管理员账号，用于应急解锁和重置密码。

6.2 配置模型

“模型”负责理解问题和生成回答，需要连接到实际模型服务。

「模型配置」→「新增配置」。
选择「内置目录」中的型号，或填写服务方提供的 Provider、Base URL、API Key 和模型名。
保存 →「连通性测试」→ 通过后「设为默认」。
「智能体」→ 编辑助手 → 选择该「默认模型」→ 保存。

参数说明：Provider 通常为 openai-compatible，地址示例为 https://llm.example.com/v1；实际参数由服务方提供。API Key 保存后只显示末 4 位掩码。

模型要求：

初始演示模型只能体验流程，正式使用需要支持工具调用的真实模型。
是否支持流式回答和读图，需要实际确认。
停用的模型不能被新会话选用。

完成后检查：新建会话，使用实际模型完成一次查询。连通性测试通过，还不能代替完整问答验证。

6.3 创建和维护用户

「用户管理」→「新建用户」。
填写用户名、显示名、初始密码、角色、数据库 Context 和每日预算。
保留「首次登录需修改密码」，保存后将网址和初始账号通过本单位规定的渠道提供给用户。
让用户登录、改密并试一次只读查询。

Context 由运维先创建，步骤见第 7.4 节。绑定哪个 Context，用户就使用对应数据库账号的权限；生产环境中，未绑定的非管理员不能执行 SQL。

管理任务	操作和影响
重置密码	用户下次登录需改密，旧登录状态立即失效；已有 API Token 需另外撤销
解锁账号	在「用户管理」解锁，无需等默认的 15 分钟
停用账号	立即生效，名下 API Token 也不能再使用
调整预算	修改每日 token 预算；预算是用量控制，不是严格费用封顶
调整角色或连接	编辑对应用户；不能修改自己的角色或停用自己，最后一个启用管理员不能降级

情况	处理方式与影响
显示「目标已变更」	连接主机、端口、节点或账号可能已变化；平台停止使用原托管口令。先核对新目标，再点击「更换」重新设置
清除托管口令	通常改用部署时的共用口令；若已关闭共用口令，该 Context 将无法执行数据库操作

6.5 管理用户组和可用范围

用户组用于批量指定哪些人能使用某个智能体或知识库，不会代替数据库账号权限。

「用户管理」→ 页面下方「用户组」，创建组并选择成员。
编辑「智能体」或「知识库」，在「可用范围」选择需要的用户组。
分别使用组内和组外账号检查可见范围与使用权限。

授权生效范围：

选择用户组后，只有组内用户和平台管理员可用；不选用户组表示所有用户可用。
智能体授权收紧后，组外用户仍可查看以前的会话，但不能继续发送消息。
技能目前不单独按用户组授权。「表注释（平台兜底）」按数据库连接隔离，不按用户组授权。

删除用户组前检查授权：只授权给该组的智能体或知识库可能变成所有人可用；按页面提示先调整资源范围。

6.6 配置智能体和技能

智能体是按任务配置的助手；技能是处理特定任务的方法说明。

在「技能」上传含 SKILL.md 的标准 ZIP 技能包，查看内容并启用。
在「智能体」编辑助手，设置用途说明、默认模型、绑定技能、可检索知识库和默认执行策略。
在「可用工具」中勾选需要的工具；不允许某类任务时取消对应勾选。
按第 6.5 节设置可用范围，再新建会话验证。

技能生效：上传技能包后还需要绑定到智能体。内置技能随平台版本更新。

工具范围：

可用工具默认全部启用，后续新增的工具也默认启用；升级后应复查。
停用的工具不会提供给模型，模型尝试调用也会被拒绝。
标为「数据出域」的工具会将数据发到平台外；不允许预测的场景，应取消该智能体的预测工具。

完成后检查：助手使用的模型、技能、知识库和可用工具符合预期，受限账号无法使用该助手。

6.7 管理知识库

新建与验证

「知识库」→「新建知识库」→「上传文档」。
在「文档」清单等待「解析中」变为「可检索」。失败时按原因处理。
用「检索测试」检查命中内容和出处；点击「前后文」查看相邻段落。
在「智能体」绑定所需知识库，并通过「可用范围」限制访问用户组。
用实际用户在对话中提问，核对回答出处。

文件与扫描件要求

项目	要求
文件格式和大小	.txt、.md、.csv、.pdf、.docx，默认单文件不超过 30 MB；旧 Word .doc 需另存为 .docx
扫描件模型	使用默认模型识别，默认模型必须支持读图；识别计入模型用量
扫描件页数	最多识别 20 页；超出上限会解析失败，应拆分后上传
文字与扫描页混合的 PDF	可能只提取文字页，请核对需要的内容是否已解析

文档更新与访问范围

同名重传：解析成功后替换旧版，失败时旧版仍可检索。
解析中断：服务重启时未完成解析的文档会标为失败，需要重新上传。
删除资料：删除文档或知识库前确认影响范围。
未绑定知识库：智能体可检索全部对当前用户可用的知识库，并不绕过用户组权限。
系统知识库：「表注释（平台兜底）」请勿改名；用户只能检索自己数据库 Context 范围的相应内容。

6.8 配置外部工具（MCP）

外部工具用于连接工单、通知等其他系统，需要管理员先登记服务并为智能体启用。外部服务应由本单位允许使用，且后端能够访问。

打开「外部工具（MCP）」→「登记 MCP 服务」。
填写名称、工具名前缀、服务地址、可选的 Authorization 授权信息和超时。
保存后查看工具清单；读取失败也会保存配置并显示原因，修正后点「刷新」。
编辑对应「智能体」，在「外部工具（MCP）」中启用该服务。
新建会话试一次允许的操作，核对审批卡和审计记录。

登记要求：

只支持 Streamable HTTP 方式的 http/https 地址；工具名前缀登记后不能修改。
授权信息加密保存，之后只显示「已设置」；平台密钥更换或丢失后，需要重新填写。

调用与停用：

调用会发送参数到外部服务，需要用户审批，并记录「数据出域」；用户可在本会话记住同一工具的批准。
停用服务后，所有智能体都不能继续调用它。
登记、修改、刷新和删除也会留下审计记录。

部署限制：需要限制可登记的服务主机，或关闭全部外部工具时，由运维按附录 A 配置。当前不支持将 TimechoAgent 作为 MCP Server 对外提供工具。

6.9 维护公共记忆、用量和平台状态

管理事项	操作与检查重点
公共记忆	在「记忆」维护共同口径和偏好，检查来源与时效，不保存个人秘密；普通用户维护自己的个人记忆
全体用量	在「用量统计」按模型、日期、智能体和用户汇总；普通用户和数据库管理员只看自己的用量。「其中估算」表示供应商未返回准确用量、按字符估算的部分
数据库通道	「执行通道」→「重新探测」，确认连接与版本正确
系统自检	请运维协助查看；错误（error）先处理，提醒（warn）确认原因。生产环境保持演示模式关闭
审批分离	按附录 A 将危险审批限制为仅数据库管理员，或开启四眼审批，让一般写入也由另一人批准
API Token	统一管理步骤见第 10 章

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

7.1 安装前检查

7.1.1 确认操作系统和权限

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

whoami
cat /etc/os-release

预期具有 root 权限。

7.1.2 确认 Docker 已安装并运行

docker --version
docker info

本次实测 Docker 版本：

Docker version 28.2.2

如果 Docker 服务未启动：

systemctl enable --now docker

7.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 与当前部署模板不兼容。

7.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。

7.2 解压和校验安装包

7.2.1 上传安装包

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

timecho-agent-0.3.0-linux-x86_64.zip

7.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

7.2.3 校验安装包完整性

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

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

7.3 配置部署环境

7.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)"

7.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 一起妥善备份。

7.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 必须与第 7.9 节创建 Context 时使用的名称完全一致。
此处只配置 Context 名称和数据库口令，不会创建数据库实例；TimechoDB 必须已在第 7.1.4 节准备完成。
Context 记录必须在第 7.9 节由管理员通过 timecho-cli 创建或确认，不能通过自然语言创建、修改或删除。

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

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

TIMECHO_BOOTSTRAP_ADMIN_PASSWORD='自定义初始口令'

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

/app/data/initial-admin-password

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

7.3.5 检查 `.env` 权限

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

预期输出：

600 root:root .env

7.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'

7.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，确认其余必填项也没有遗漏。

7.6 启动服务

7.6.1 启动

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

首次启动会依次完成：

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

7.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 验证安装结果

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.7.2 服务器 IP 验证

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

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

7.7.3 浏览器访问

打开：

http://<TimechoAgent_IP>:8080/

7.8 首次登录

7.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 中配置的值登录。

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

7.8.2 登录并修改口令

使用用户名 admin 和第 7.8.1 节查到的初始口令登录 Web 控制台。

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

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

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

7.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 "初始口令文件已删除"'

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

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

配置步骤：

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

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

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

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

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

7.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 基于安全考虑设置的能力限制，不应尝试通过提示词绕过。

7.9.1 准备连接信息

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

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

7.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 已存在，应先查看其配置。

7.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；不要通过自然语言删除。
管理员完成变更后，应通知使用者重新验证连接，避免继续使用旧地址或旧凭据。

7.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。

7.9.5 绑定用户

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

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

生产环境建议：

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

7.10 服务启停命令

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

以下命令均在 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 配置。

7.11 故障排查

7.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

7.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

7.11.3 后端启动失败

查看日志：

docker compose logs --tail=300 backend

常见原因：

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

7.11.4 前端没有启动

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

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

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

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

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

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

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

7.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 限制。

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

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

处理方式：

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

8. 日常运维（运维人员阅读）

8.1 平时检查什么

日常巡检不只检查容器是否运行，还要检查日志、磁盘、内存、模型服务、数据库执行通道和备份状态。服务启停命令见第 7.10 节。

检查项	检查重点
服务状态	`postgres`、`backend`、`frontend` 均正常运行且状态为 healthy
后端日志	没有持续出现异常、反复重启、数据库连接失败或模型调用失败
数据库和模型	用户能够完成一次真实只读查询和一次模型连通性验证
磁盘和内存	Docker 数据目录空间充足，内存使用没有持续增长
备份	最近一次备份成功、文件可读取，并已复制到其他机器或存储
日志和审批	失败请求、异常登录、超时操作和待处理审批均已检查

基本检查命令：

cd /opt/timecho-agent/deploy

docker compose ps
docker compose logs --since 1h backend
docker compose logs --since 1h frontend
docker stats --no-stream
df -h / /var/lib/docker

检查结果时重点关注：

三个服务是否均处于 healthy 状态；
后端是否持续输出错误或反复重启；
PostgreSQL 是否存在连接失败或磁盘空间不足；
模型服务是否出现鉴权失败、超时或额度错误；
Docker 数据目录是否仍有足够可用空间；
最近一次备份是否成功并可以读取。

服务显示 healthy 不代表模型和数据库执行通道全部正常，还需要完成业务验证：

使用管理员查看 /api/v1/system/status，确认系统自检结果；
在受控的内部网络或本机端口检查 /actuator/health/readiness；
使用普通用户完成一次真实只读查询；
在模型配置页面执行一次连通性测试；
检查用户是否绑定正确的数据库 Context；
确认最近的审批和审计记录没有异常。

如果发现问题，先记录发生时间、用户、会话标题、错误编号和相关日志，再按照第 8.2 节处理。

8.2 用户报错时怎么处理

处理用户问题前，先记录以下信息：

平台版本和部署方式；
问题发生时间；
用户账号、会话标题和操作步骤；
页面提示、错误编号和预期结果；
是否已经产生数据库写入；
相关的后端或前端日志。

问题	优先检查
页面打不开、接口返回 502	网络入口、反向代理、前端和后端状态
登录成功后立即回到登录页	HTTPS、Cookie、`Set-Cookie` 和反向代理配置
无法查询数据库	Context 是否存在、用户是否绑定、数据库地址、端口、权限和口令
模型超时或回答失败	模型连通性、API Key、网关额度、超时和流式配置
知识库检索不到内容	文档索引状态、文字层、关键词、知识库和智能体绑定范围
上传失败	文件格式、单文件大小、总请求大小和反向代理请求体限制
回答一次性出现或中途断开	代理缓冲、压缩、读取超时和流式配置
API Token 调用失败	Token 是否过期或撤销、账号状态、请求头和角色权限
模型密钥或数据库口令无法解密	`TIMECHO_SECRET_KEY` 是否被修改或丢失
写入或删除操作超时	先确认目标数据是否已经发生变化，再决定是否重试

查看最近的后端日志：

cd /opt/timecho-agent/deploy
docker compose logs --since 1h backend

修改 .env 后，先检查配置，再重新创建或启动服务：

docker compose config -q
docker compose up -d
docker compose ps

写入、修改或删除操作发生超时时，不要直接重复提交。应先确认数据库中的实际状态，并保留必要日志。

如果问题仍无法解决，按第 11.2 节准备脱敏后的版本信息、错误编号、操作步骤和日志，联系对应的管理员或天谋团队。

8.3 日志、监控与清理

日志检查

查看最近一小时的日志：

cd /opt/timecho-agent/deploy
docker compose logs --since 1h backend
docker compose logs --since 1h frontend

查看指定数量的最近日志：

docker compose logs --tail=200 backend

持续观察后端日志：

docker compose logs -f backend

生产环境不要长期启用调试日志。日志中如包含用户信息、数据库地址或错误上下文，应按组织要求进行访问控制和脱敏。

资源和监控

定期检查容器资源和磁盘空间：

docker stats --no-stream
df -h / /var/lib/docker
docker system df

指标监控默认关闭。启用 Prometheus 指标时：

使用独立的指标抓取令牌；
不要使用管理员登录令牌代替指标令牌；
只允许监控网络访问指标端点；
限制指标端点的访问来源；
按附录 B 配置抓取任务。

数据清理

数据	清理建议
审计记录	按组织保留期限定期归档或清理
已删除会话	定期检查回收站和过期数据
会话附件和导出文件	下载所需成果后清理旧文件
Docker 日志	配置日志轮转，避免占满磁盘
备份文件	按备份保留策略清理过期备份，并保留异地副本
知识库和公共记忆	由有权限的管理员定期维护，删除过期内容

清理前先确认数据范围和备份状态。不要使用未经确认的 docker compose down -v 或 Docker 卷清理命令，以免删除平台数据库、附件和 Context 配置。

8.4 管理员忘记密码

优先使用备用管理员账号重置或解锁管理员账号。

如果所有管理员都无法登录，按以下受控流程处理：

准备符合密码策略的临时随机口令；
在后端配置中加入 TIMECHO_SECURITY_ADMIN_RECOVERY_PASSWORD；
检查配置并重建后端服务；
使用临时口令登录管理员账号；
立即设置新的正式口令；
删除临时恢复配置；
再次重建后端服务；
确认系统日志不再提示恢复口令遗留，并确认旧登录令牌已经失效。

配置修改后执行：

cd /opt/timecho-agent/deploy
docker compose config -q
docker compose up -d
docker compose ps
docker compose logs --tail=200 backend

恢复口令只用于受控恢复，不要写入普通文档、聊天记录或工单正文。完成恢复后，应检查管理员账号、备用管理员、API Token 和审计记录。

9. 备份、恢复与升级（运维人员阅读）

9.1 需要备份什么

对象	内容
平台 PostgreSQL	用户、会话、模型配置、审批、审计、用量、知识库、文档附件文字、工作区、托管数据库口令、API Token 和外部服务配置
backend-data	对话图片、导出文件，以及可能自动生成的密钥等
cli-config	数据库 Context 配置
.env、override 和相关密钥	密码、加密密钥、登录签名、指标令牌等
镜像和部署材料	同版本恢复所需镜像、模板、发布记录及反代配置

密钥加密单独保管，备份复制异地并定期恢复演练。backend-data 若含自动生成密钥，也属于敏感材料。

平台备份不包含 TimechoDB/IoTDB 的业务数据。 恢复平台也不会撤销已经执行的业务数据库写入，目标库由 DBA 独立备份。

9.2 内置业务库的备份示例

验证范围：内置 PostgreSQL 的备份与恢复已在内部测试环境演练；外部 PostgreSQL 的备份命令和定时备份任务尚未验证。实际部署前，应在目标环境完成一次备份恢复演练。升级的验证范围见第 9.4 节。

日常在线备份

在同一 Bash 会话执行，目录需可写且空间充足：

set -euo pipefail
umask 077
cd /opt/timecho-agent/deploy
B="/var/backups/timecho-agent/$(date +%F-%H%M%S)"
mkdir -p "$B"
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' > "$B/db.dump"
docker compose exec -T backend tar czf - -C /app/data . > "$B/backend-data.tgz"
docker compose exec -T backend tar czf - -C /app/home/.config/timecho-cli . > "$B/cli-config.tgz"
docker compose exec -T postgres pg_restore --list < "$B/db.dump" > "$B/db-manifest.txt"
tar tzf "$B/backend-data.tgz" > /dev/null
tar tzf "$B/cli-config.tgz" > /dev/null
(cd "$B" && sha256sum db.dump backend-data.tgz cli-config.tgz > SHA256SUMS)

另行安全备份 .env、override、密钥及部署材料。备份完成后复制到异地，并定期进行恢复演练。

升级前的停写备份

在线备份中的数据库与随后打包的附件不是同一瞬间的快照。升级前或要求严格恢复点时，通知用户暂停使用，保持 postgres 运行，停止前后端后备份：

set -euo pipefail
umask 077
cd /opt/timecho-agent/deploy
B="/var/backups/timecho-agent/maintenance-$(date +%F-%H%M%S)"
mkdir -p "$B"
docker compose stop frontend backend
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' > "$B/db.dump"
docker compose run --rm -T --no-deps --entrypoint tar backend czf - -C /app/data . > "$B/backend-data.tgz"
docker compose run --rm -T --no-deps --entrypoint tar backend czf - -C /app/home/.config/timecho-cli . > "$B/cli-config.tgz"
docker compose exec -T postgres pg_restore --list < "$B/db.dump" > "$B/db-manifest.txt"
tar tzf "$B/backend-data.tgz" > /dev/null
tar tzf "$B/cli-config.tgz" > /dev/null
(cd "$B" && sha256sum db.dump backend-data.tgz cli-config.tgz > SHA256SUMS)

备份完成后
- 保存材料：另行保存同一恢复点的密钥、.env、override 和部署文件。
- 校验失败：保留日志、先解决问题，不继续升级。
- 仅做备份：成功后运行 docker compose up -d 并验证。
- 接着升级：保持应用停止。

外部 PostgreSQL：由 DBA 按其规范备份，仍要保存附件、Context 和密钥，不使用内置 postgres 容器命令。

9.3 恢复示例

恢复会覆盖目标平台数据。 先确认恢复点、目标环境和当前数据的保存方案，再执行。

开始前确认：

同版本镜像和配置已准备，密钥与备份一致。
使用新环境或已准备好的空数据卷。
目标附件和 CLI 配置卷必须为空；不能把文件直接解包到正在使用或已有数据的卷中，以免混入其他时间点的文件。

内置 PostgreSQL 示例：

set -euo pipefail
cd /opt/timecho-agent/deploy
B="/var/backups/timecho-agent/<已确认的备份目录>"
(cd "$B" && sha256sum -c SHA256SUMS)
docker compose config -q
docker compose down
docker compose up -d --wait postgres

# 以下删除并重建当前项目的业务库，必须先确认目标
docker compose exec -T postgres sh -c 'dropdb -U "$POSTGRES_USER" --if-exists "$POSTGRES_DB" && createdb -U "$POSTGRES_USER" "$POSTGRES_DB"'
docker compose exec -T postgres sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --no-owner --exit-on-error' < "$B/db.dump"

# 目标卷须为空；一次性容器只解包，不启动后端
docker compose run --rm -T --no-deps --entrypoint tar backend xzf - -C /app/data < "$B/backend-data.tgz"
docker compose run --rm -T --no-deps --entrypoint tar backend xzf - -C /app/home/.config/timecho-cli < "$B/cli-config.tgz"
docker compose up -d
docker compose ps

外部业务库：先由 DBA 恢复到空库，再恢复两个应用卷并启动。日常停止不要使用 docker compose down -v，以免删卷。

恢复后检查：

原账号能登录，会话、知识库、附件和工作区完整。
模型 Key、托管数据库口令与外部服务授权能解密。
数据连接可用，真实只读查询成功。
使用 API Token 或外部工具时，再核对对应配置和调用。

恢复边界：备份之后的平台数据不会自动回来，待审批请求也不会继续执行。

9.4 升级与回滚

升级前准备

升级前应完成以下工作：

阅读目标版本发布说明；
在测试环境完成升级和恢复验证；
确认新旧版本的 Compose 模板和 PostgreSQL 大版本；
通知用户停写并安排维护窗口；
备份平台 PostgreSQL、backend-data、cli-config、.env、密钥和部署材料；
保留旧镜像、旧配置和旧数据卷；
确认同一个平台数据库不会同时被两个后端实例使用。

同一 PostgreSQL 大版本下升级

cd /opt/timecho-agent/deploy

docker compose stop frontend backend
docker load -i /path/to/timecho-agent-<新版本>-images.tar.gz
# 按发布说明更新 .env 和 Compose 模板
docker compose config -q
docker compose up -d
docker compose logs --tail=200 backend
docker compose ps

启动后依次验证：

后端和前端状态；
/api/v1/system/info 或系统状态接口；
管理员登录；
模型连通性；
Context 和只读查询；
知识库、会话、附件和工作区；
审批、审计和 API Token。

PostgreSQL 16 升级到 18

PostgreSQL 大版本升级不能只替换镜像并复用旧数据卷，必须执行导出和恢复：

停止前端和后端，保留旧 PostgreSQL 服务；
使用 pg_dump 导出旧数据库；
创建 PostgreSQL 18 的新空数据库；
使用 pg_restore 导入备份；
恢复 backend-data、cli-config 和同一恢复点的密钥；
更新 Compose 配置并启动新服务；
验证登录、模型、Context、知识库、附件和审计；
验证通过后再安排旧环境下线。

升级前必须保留旧镜像、旧配置和旧数据卷。不能把 PostgreSQL 18 镜像直接挂载到 PostgreSQL 16 的数据目录上。

回滚

应用数据库结构发生迁移后，不能依赖新版本自动降级。回滚应使用：

升级前的旧镜像；
升级前的旧 Compose 模板和 .env；
升级前的完整数据库备份；
升级前的 backend-data 和 cli-config；
与备份匹配的加密密钥。

恢复前先保存升级后产生的新数据，再按照第 9.3 节恢复流程处理。回滚完成后必须验证管理员登录、数据库只读查询、模型调用、知识库和附件。

升级和回滚会中断对话，并可能使未处理的审批失效。操作完成后，应通知用户恢复使用。

9.5 主机故障后的冷备切换

切换前提：一个平台数据库只能运行一个后端，不支持多副本同时工作。外部业务库仍正常时，先判断是否只需切换应用主机，不为了切换主动恢复旧备份。

确认原后端已停止或隔离。
在备机恢复同版本配置和数据。
按第 9.3 节检查通过后，切换访问入口。
原主机恢复后，保持旧后端停止。

仍无法启动时：若确认原主已停止或隔离后，仍提示另一个实例在使用业务库，请由数据库管理员排查，或联系天谋团队协助。问题解决后再启动新实例。

10. API Token 与接口接入

本章供需要脚本或其他系统接入的用户阅读；日常使用网页无需创建 API Token。

10.1 创建和使用自己的 Token

API Token 是提供给脚本使用的凭据，权限与本人账号相同，应像密码一样保管。

登录网页，在右上角用户菜单打开「API Token」。
新建 Token，填写便于识别用途的名称，选择 30 天至 1 年的有效期，也可选择不过期。
创建后立即复制并安全保存；明文只显示这一次。
脚本请求使用请求头 Authorization: Bearer <API_TOKEN>；不要把 Token 放在 URL、共享文档或代码仓库中。
不再使用时点击「撤销」，立即失效。

使用限制：Token 不能用于创建新的 Token 或修改密码。

泄露后处理：修改密码不会自动撤销已有 Token；需要明确撤销对应 Token。

10.2 管理员统一撤销 Token

平台管理员在用户菜单 →「API Token」打开「全部人的」，可查看名称、前缀和最近使用时间，并撤销对应 Token。

员工离职时停用账号，名下 Token 也无法继续使用；新建和撤销 Token 都会留下审计记录。

10.3 查看接口文档并验证接入

打开接口文档

接口文档默认关闭；由运维在部署配置中设 TIMECHO_API_DOCS_ENABLED=true 并重建服务。
平台管理员访问平台网址下的 /api/v1/docs。
在「Authorize」填入个人 API Token，查看和试调接口。

访问权限：OpenAPI 描述位于 /api/v1/openapi。普通用户和数据库管理员不能访问上述两个文档入口。

发送只读请求

管理员只读接入示例，替换域名和 Token 后执行：

curl -fsS https://agent.example.com/api/v1/system/status \
  -H 'Authorization: Bearer <API_TOKEN>'

成功的标志：返回系统自检结果，响应中包含各检查项的状态、级别和说明。

返回状态	优先检查
401	Token 是否完整、过期或撤销，以及账号是否已停用
403	角色、首次改密要求和接口权限

继续集成：按本平台版本的接口文档开发。API Token 不会绕过数据库账号权限、预算和审批规则；批量调用、流式对话或其他接口集成需要进一步支持时，请联系天谋团队。

11. 常见问题与支持

如果问题发生在安装、启动或 Context 配置阶段，请参阅第 7.11 节。

11.1 常见提示怎么处理

提示	你可以怎么做
账号已锁定	等待锁定结束，或请管理员解锁
请先修改密码	按页面提示改密，再继续
账号未绑定数据库 Context	请平台管理员完成数据访问配置
该会话正在生成中	等本轮结束，或点「停止生成」；检查是否在另一个标签页发送过
审批已失效、审批超时	确认原操作未执行后重新提出，请审批人重新审核
该语句已被拒绝	与审批人沟通，不直接重复提交
今日预算用完	联系管理员，或次日再使用
上下文过长	先生成摘要，或新建会话
上传失败、文件过大	压缩/拆分资料，或联系管理员检查限制
服务内部错误，带编号	记录编号、时间、会话标题和步骤，交给管理员
没有权限使用智能体或知识库	请管理员检查用户组和可用范围设置
工具未对当前智能体启用	请管理员在智能体设置中启用该工具，或改用其他智能体
已自动压缩较早对话	系统已生成摘要，最近对话仍可继续使用
没有配置 Timecho AI 密钥	预测功能暂不可用，请联系平台管理员
连接目标与托管口令不一致	请管理员核对数据库连接，再在「执行通道」重新设置口令
扫描件识别失败或只识别了部分页面	确认模型支持读图；超过页数上限时拆分，检查未识别的页面
外部工具清单为空、调用失败	请管理员检查服务地址、授权信息、网络连通和智能体是否已启用该服务
请求缺少有效的防跨站令牌	刷新页面后重试；脚本接入使用 API Token
登录或改密操作过于频繁	稍等后再试；多用户同时受影响时请运维核查代理的真实 IP 配置

查询失败可以按提示处理。写入或删除失败时，先检查审批和实际数据状态，再决定是否重试，避免重复执行。

11.2 获取支持

情况	建议联系
忘记密码、账号锁定、数据访问未配置、预算不足	本单位平台管理员
审批、数据库权限和操作结果核对	本单位数据库管理员
获取安装包、版本兼容、部署方案、问题无法排除、恢复或升级失败	天谋团队

如需额外的接口集成、数据导入、预测能力或其他部署方案，请联系天谋团队确认适用版本与支持范围。

需要天谋团队协助时，通过项目对接人或既有服务渠道联系。尽量提供：

「关于」中的版本信息及部署方式。
问题发生时间、操作步骤和预期结果。
错误文字、报错编号，以及必要的日志或界面截图。
是否影响生产、是否已产生写入，以及已做过哪些处理。

截图和日志先脱敏，不发送密码、API Key、登录令牌、完整 .env 或非必要业务明细。紧急问题先保存现场；未经核对，不反复执行写操作或删除数据卷。

附录

A. 常用配置

以下为日常安装和维护常用的配置。按需要修改，未列出的参数保持安装包默认值。

场景	配置与默认值
严格分离危险审批	TIMECHO_APPROVAL_DANGER_APPROVER_ROLES=DB_ADMIN；默认 DB_ADMIN,ADMIN
调整审批等待	TIMECHO_AGENT_APPROVAL_TIMEOUT_SECONDS=600
调整查询超时	TIMECHO_CLI_TIMEOUT_SECONDS=30
网关不支持流式	TIMECHO_LLM_STREAM=false；默认 true
慢模型需要更长超时	TIMECHO_LLM_REQUEST_TIMEOUT_SECONDS=120
模型地址防私网	TIMECHO_SECURITY_BLOCK_PRIVATE_MODEL_ENDPOINTS=false；模型网关不在内网时建议设为 true
默认每日预算	TIMECHO_BUDGET_DAILY_TOKENS_PER_USER=0（不限），用户单独设置优先
预算日界	TIMECHO_BUDGET_ZONE=Asia/Shanghai
审计保留	TIMECHO_AUDIT_RETENTION_DAYS=180，0 表示永久，不能少于 180 天
后端内存	BACKEND_MEM_LIMIT=2g
指标抓取	TIMECHO_SECURITY_METRICS_TOKEN，非空至少 32 字节
四眼审批	TIMECHO_APPROVAL_FOUR_EYES=off/write/all
写操作逐次审批	TIMECHO_APPROVAL_SESSION_AUTO_WRITE=false
回收站保留	TIMECHO_SESSIONS_TRASH_RETENTION_DAYS=30
自动摘要阈值	TIMECHO_AGENT_SUMMARY_TRIGGER_RATIO=0.8
预测服务	TIMECHO_AI_BASE_URL=https://ai.timecho.com、TIMECHO_AI_MAX_ROWS=2000
查询导出	TIMECHO_EXPORT_MAX_ROWS=100000、TIMECHO_EXPORT_MAX_BYTES=52428800（50 MB，填写字节数）
对话文档大小	TIMECHO_DOCUMENTS_MAX_BYTES=20971520（20 MB）
对话文档数量	TIMECHO_DOCUMENTS_MAX_PER_SESSION=20
扫描件识别	TIMECHO_DOCUMENTS_OCR_ENABLED=true、TIMECHO_DOCUMENTS_OCR_MAX_PAGES=20
外部工具总开关	TIMECHO_MCP_ENABLED=true
外部工具允许主机	TIMECHO_MCP_ALLOWED_HOSTS，多个主机以逗号分隔；默认空，表示不限
禁止外部工具私网地址	TIMECHO_MCP_BLOCK_PRIVATE=false；改为 true 会拒绝私网及回环服务
接口文档	TIMECHO_API_DOCS_ENABLED=false；开启后仅平台管理员可访问
登录 Cookie 安全设置	TIMECHO_SECURITY_COOKIE_SECURE=auto；纯 HTTP 下不设为 true

新增后端环境变量时，在 deploy/ 创建 docker-compose.override.yml，例如：

services:
  backend:
    environment:
      TIMECHO_APPROVAL_DANGER_APPROVER_ROLES: DB_ADMIN
      TIMECHO_AGENT_APPROVAL_TIMEOUT_SECONDS: "900"

加载配置：将 .env 的 COMPOSE_FILE 改为 docker-compose.prod.yml:docker-compose.override.yml，然后执行 config -q 和 up -d。

注意：只在 .env 新增一行，不保证变量会被传进后端；单纯 restart 也不会加载新的环境变量。

B. 启用指标监控

接入 Prometheus 时，按以下步骤配置：

指标端点及本机端口映射已有内部测试记录；下面的 Prometheus 抓取配置本身尚未实测，需在目标环境验证。

在受控 .env 中填写 TIMECHO_SECURITY_METRICS_TOKEN，至少 32 字节随机值，可使用 openssl rand -hex 24 生成。妥善保存，不作为用户登录密码使用。
将下面端口映射合并到 docker-compose.override.yml。已有 backend 配置时合并字段，不重复定义 services/backend：
```
services:
  backend:
    ports:
      - "127.0.0.1:8090:8090"
```
按附录 A 设置 COMPOSE_FILE，执行 docker compose config -q，再 docker compose up -d。

将以下抓取配置合并到同一宿主上的 Prometheus 配置，替换令牌，并按其管理方式加载：

scrape_configs:
  - job_name: timecho-agent
    metrics_path: /actuator/prometheus
    authorization:
      credentials: <指标抓取令牌>
    static_configs:
      - targets: ["127.0.0.1:8090"]

令牌配置文件限制读取权限。Prometheus 在另一主机或容器时，127.0.0.1 指向它自身；可让 Prometheus 加入应用的内部网络，使用 backend:8090，不将后端端口开放公网。

成功的标志：Prometheus 目标正常，返回 JVM、CPU、HTTP 或连接池等指标。404 时检查令牌是否已配置、是否经前端访问；401 时检查是否使用正确的指标令牌。

在同一宿主验证数据库执行就绪：

curl -fsS http://127.0.0.1:8090/actuator/health/readiness

健康检查成功后，再验证一次真实模型查询。