日常运维

大约 6 分钟

日常运维

1. 平时检查什么

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

检查项	检查重点
服务状态	`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；
确认最近的审批和审计记录没有异常。

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

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

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

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

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 指标时：

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

数据清理

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

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

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 和审计记录。