Haitao Pan 8b8a2aa3fa feat(agent-persistence): implement PostgreSQL persistence for agent registry

Core Changes:
- Add Agent struct and management methods to Store interface
- Implement PostgreSQL store methods (UpsertAgent, ListAgents, DeleteAgent, DeleteStaleAgents)
- Integrate persistence into Registry with async database writes
- Add Load() method to restore agents from database on startup
- Implement runAgentCleanup background task (5min interval, 10min stale threshold)

Database:
- Update agents table schema to use JSONB for groups field
- Add indexes on last_heartbeat and healthy columns
- Support health tracking and automatic cleanup of stale agents

Documentation:
- Add comprehensive DB access and upgrade guide
- Include agent persistence implementation plan
- Document diagnostic procedures and troubleshooting steps
- Add walkthrough of multi-agent support implementation

This enables:
- Persistent agent state across service restarts
- Automatic cleanup of offline agents
- Multi-agent support with shared token authentication

2026-02-05 08:34:25 +08:00

2.4 KiB

Raw Permalink Blame History

数据库访问与系统升级指南

本文档介绍如何通过 stunnel 安全访问数据库,执行 Agent 持久化迁移,以及验证系统状态。

1. 数据库访问 (DB Access via stunnel)

为了安全地从本地或开发环境访问生产数据库,我们使用 stunnel 隧道。

配置说明

配置文件: deploy/stunnel-account-db-client.conf
本地监听: 127.0.0.1:15432
上游连接: postgresql.svc.plus:443

启动方式

您可以使用 Makefile 中的快捷命令:

# 启动 stunnel 隧道
make stunnel-start

或手动启动:

stunnel deploy/stunnel-account-db-client.conf

连接验证

启动后,可以使用 psql 连接:

psql "postgres://postgres:${POSTGRES_PASSWORD}@127.0.0.1:15432/account?sslmode=disable"

2. 升级与迁移 (Upgrade & Migration)

Agent 持久化迁移 (2026-02-05)

本次升级新增了 agents 表,用于存储各节点的运行状态。

执行迁移: 通过隧道连接后,运行以下脚本:

psql "postgres://postgres:${POSTGRES_PASSWORD}@127.0.0.1:15432/account?sslmode=disable" -f sql/20260205_agents_table.sql

验证迁移: 确认表和索引已存在:

psql "postgres://postgres:${POSTGRES_PASSWORD}@127.0.0.1:15432/account?sslmode=disable" -c "\dt agents"

3. 系统验证 (Verification)

Agent 注册验证

部署新代码后,观察日志确认 Agent 正确自报 ID 并注册:

查找关键词: agent status updated
检查 agentID 字段是否为 hk-xhttp.svc.plus 等具体 ID 而非 *。

数据库持久化验证

查询 agents 表确认数据已填充:

SELECT id, healthy, last_heartbeat, clients_count, sync_revision FROM agents;

自动清理验证 (Stale Cleanup)

系统每 5 分钟执行一次清理,自动删除 10 分钟未更新心跳的 Agent。

观察日志关键词: cleaned up stale agents

4. 常见问题调试 (Debugging)

401 Unauthorized (`invalid_agent_token`)

检查: 确认 Agent 端的 apiToken 与 Cloud Run 的环境变量 INTERNAL_SERVICE_TOKEN 完全一致。
配置路径: Agent 节点的 /etc/agent/account-agent.yaml。

500 Internal Server Error (`/api/agent/nodes`)

检查: 访问 /api/agent/nodes 时若报错,请检查 accounts.svc.plus 的环境变量。
修复: 确保 INTERNAL_SERVICE_TOKEN 已正确设置。

2.4 KiB Raw Permalink Blame History