健康、升级与审计

先确认系统健康，再按维护流程升级；遇到问题时结合审计和用户反馈定位。

系统健康与索引重建

健康项目

页面展示：

• API、数据库和 Redis。
• 本地密码登录保护与认证邮件。
• 知识库文档解析。
• 知识库检索与索引。
• 可选结果重排。
• runner、工作区可读写状态。
• 权威运行槽、实际运行轮次、恢复状态、子进程数和并发上限。
• Docker 部署中 API、Runner、worker、Web、网关、PostgreSQL 和 Redis 等容器的 CPU、内存、PID 与运行状态。

页面只显示脱敏摘要和检查建议，不显示连接串、密码、Token、密钥、Redis key 或完整内部日志。

理解总体状态

• liveness 表示 API 进程仍在运行。
• readiness 表示关键依赖是否可以承接完整流量。
• MinIO 等必要存储失败会使 readiness 不可用，但进程继续探测。
• Docling 或知识检索外部服务不可用会单独标记相应能力，不一定使整个 LinkSense 不可用。
• Ranker 未配置是合法状态，失败时使用 RRF。

服务资源占用

“服务资源占用”展示最近一次可用的 Docker 容器快照。无法观测通常表示 Runner 控制器没有可用的 Docker socket 或权限；它不等同于所有容器已经停止。资源卡只用于诊断，不会从页面重启或停止容器。

磁盘占用

“磁盘占用”位于顶部健康摘要，只展示当前部署的总占用。它包含所有用户的项目空间、任务产物与附件、运行环境与缓存，以及数据库、知识库索引、备份、日志和服务程序。已完成或归档任务仍保留的文件也会计入。

统计使用文件系统已分配空间，稀疏文件按实际占用计算；共享目录、硬链接和镜像层只计一次，实际保留的不同副本分别计入。这不是服务器整块磁盘的使用量，也不包含其他部署、全局构建缓存或无法确认归属的历史镜像。多个部署共同挂载的存储无法单独归属时会列为未统计。外部服务器上的数据库、对象存储和索引不计入本机占用，应在相应服务单独查看。

系统启动后先采集一次，此后每小时在后台更新；上次扫描未结束时不会并发启动。大目录扫描有独立的时间与资源限制。其他健康信息先正常显示，磁盘占用在首次完整统计返回后自动加入顶部摘要；扫描未完成或结果不完整时，不显示磁盘占用，也不把残余数据当作总量。最近统计时间可通过悬停查看。采集不阻塞健康检查或任务执行，失败不直接改变服务就绪状态。

Docker 部署使用已有 Worker 镜像启动只读、无网络的临时采集容器，不读取文件内容，完成后移除。需要现有 Docker socket 权限及允许只读扫描的容器能力；存储驱动无法提供镜像层或可写层位置时，相应分类显示未统计。本机进程部署暂时无法提供完整的部署磁盘统计。

本功能没有数据库迁移，也不搬迁、清理或改写已有用户文件。更新 Runner、API 和 Web 后即可读取既有空间；不需要重新创建任务、项目或应用。

清理失败资源

任务或能力删除后的异步清理多次失败时，健康页会列出资源类型、清理阶段、稳定原因和尝试次数。可以重试单项或全部失败项；系统会重新核对状态，仍在使用的目标任务会延后清理，其他运行中任务不会被中断。

路径边界、权限或运行状态无法确认时，不要手工删除受控目录。先按页面原因修复部署权限或 Runner，再从健康页重试。

全量重建知识库索引

切换 Embedding 模型或发现部署范围索引不一致时，页面会提示重建：

1. 确认模型与维度配置已经稳定。
2. 选择全量重建并阅读影响。
3. 在维护窗口启动。
4. 持续查看进度和失败数。
5. 完成后验证知识库检索状态。

重建有部署级并发上限，失败项会保留可重试状态。不要通过重复点击并行启动多个重建。

故障升级

按建议检查项由有部署权限的人员处理环境变量、网络或外部服务。健康页不会自动启动、重建或管理 Docling、Elasticsearch、模型服务等外部容器。

检查并升级 LinkSense

查看版本状态

页面自动检查 LinkSense 的 GitHub 正式发布，显示当前版本、最新版本、检查时间、发布时间和发布说明。可以选择“立即检查”刷新结果，或打开 GitHub 发布页核对完整信息。

检查失败不会影响其他业务功能。页面会区分无法连接 GitHub、请求受限和响应无法识别；修复服务器出站网络或等待限制解除后重试。

有新版本时管理员会在主界面看到提示。关闭提示只对当前管理员和当前版本生效，新版本发布后仍会再次显示。

升级前准备

1. 阅读从当前版本到目标版本的发布说明。
2. 安排业务低峰维护窗口，并在“系统设置 → 系统维护”通知用户。
3. 确认部署主机磁盘空间、Docker 服务和 PostgreSQL 备份位置可用。
4. 等待或停止不应跨升级继续运行的任务，并确保管理员仍能访问系统健康页。

在部署主机执行

Linux：

curl -fsSL https://raw.githubusercontent.com/LingX-AI/linksense/main/upgrade.sh | sudo sh

macOS（不要使用 sudo）：

curl -fsSL https://raw.githubusercontent.com/LingX-AI/linksense/main/upgrade.sh | sh

脚本会识别 Core 或 Full 版本，等待运行中的任务结束，并在数据库迁移前创建经过验证的 PostgreSQL 备份。保存脚本输出的备份地址；数据库迁移开始后的失败不会自动回滚数据库。

从 main 分支部署的实例

使用 deploy/production/deploy-production.sh 的实例默认直接切换版本，不等待任务自然完成。新版本先构建，再进入维护并停止进行中的任务。已有对话和文件保留，未完成及排队请求不会自动重跑，用户需检查实际进度后手动继续。任务已经发送的消息或其他外部操作不会撤销。

停止任务使用共享的短暂宽限窗口，不随任务数量逐个累加等待。备份、迁移确认和健康检查仍会执行。若任务中止或状态保存失败，部署会明确报错并保留维护；管理员排除报错后重新执行部署，而不是直接重启旧服务。

升级后验证

进入“系统健康”确认 API、数据库、Redis、存储、Runner、知识解析与检索等项目恢复；再创建一个最小任务验证执行链路。确认无误后提前关闭维护或等待维护窗口自动结束。

升级失败时保留终端输出和备份地址，由有部署权限的人员按发布说明处理。不要在未确认数据库状态时反复运行升级脚本。

审计日志

可以查询的事件

审计区分三个数据范围：

• 永久审计日志：账号与角色、用户组、插件/Skill 导入和发布、凭据生命周期、知识库治理、模型和系统设置，以及管理操作结果。
• 任务执行元数据：跨用户的脱敏执行摘要、状态、能力名称和文件数量，不含标题、正文或下载入口。
• 已删除任务产物：永久保留产物的数量、大小、校验状态和删除时间，不提供内容查看、恢复或下载。

使用页面筛选条件按时间、操作者、目标类型、动作或结果缩小范围。任务执行元数据还可按插件、Skill、错误码、Runner 状态、归档状态及创建/运行日期筛选。选择记录可在详情抽屉查看稳定动作、必要 ID、时间和结构化脱敏元数据；界面不会把协议原始字段直接暴露为用户内容。

内容边界

管理员审计不会显示：

• 其他用户任务正文、附件或成果内容。
• 完整工具参数或第三方原始响应。
• 密码、Token、API Key、凭据明文。
• 完整 Base URL、连接串或内部路径。

某些记录保留来源 IP 和 User-Agent 作为受限审计元数据；界面按安全策略展示，不用于普通用户查询。

被拒绝的操作

自我停用、降级自己、尝试停用最后一个管理员、越权读取和无效治理请求也会记录结果与稳定错误码。被拒绝记录有助于区分误操作和异常尝试。

使用建议

• 先限定时间范围，再按目标或动作筛选。
• 导出或转述时继续遵循组织的数据最小化政策。
• 将审计事实与系统健康时间点结合排查，不要把缺少正文误认为记录不完整。
• 审计记录是永久安全历史；业务父实体删除后仍保留最小 ID、类型和影响数量。

管理用户反馈

查看反馈

列表按页显示提交用户、正文摘要、图片数量、回复状态和提交时间。选择“查看”可阅读完整正文并打开图片预览；图片加载失败时刷新页面再试，不要要求用户通过不受控渠道发送敏感原图。

反馈可能包含用户主动提交的业务信息。只为问题定位使用，避免复制到日志、公开任务或无关外部服务。反馈页不是审计日志，也不自动关联具体任务执行记录。

回复用户

打开反馈详情，在“回复用户”中输入文字或添加图片后选择“发送回复”。支持纯文字、纯图片和图文回复；每次最多 2,000 个字符、9 张图片，每张不超过 5 MB，支持 PNG、JPEG、WebP 和 GIF。也可以直接粘贴图片。

同一条反馈可多次回复，回复按时间排列。发送失败时草稿和所选图片会保留。成功发送后，用户可在“我的反馈”查看回复；列表状态变为“已回复”，不自动表示问题已解决。

删除反馈

删除会永久移除反馈正文、所有回复及其全部图片，无法恢复。确认已经完成必要处理并符合组织保留要求后再删除。删除反馈不会删除提交用户、任务、审计记录或用量事实。

处理建议

• 优先使用用户提供的发生时间、页面和稳定错误码定位问题。
• 需要更多信息时通过组织认可的沟通渠道联系提交者。
• 不要索取密码、Token、API Key、二维码或一次性链接。
• 涉及系统故障时结合系统健康和审计日志核对。