portagent 容器升级体验差：数据目录路径和用户权限变更导致数据丢失

[deepracticexs]

问题描述

从 portagent:1.3.0 升级到 portagent:latest 后，原有用户账户数据无法读取，表现为"账户丢失"。

根本原因

新版本容器存在两个破坏性变更：

1. 数据目录路径变更

• 旧版本: /home/agentx/.agentx
• 新版本: /home/node/.agentx (AGENTX_DIR 环境变量)

如果用户按照旧版本的 docker-compose.yml 挂载到 /home/agentx/.agentx，新版本将无法读取数据。

2. 容器用户变更

• 旧版本: agentx 用户 (uid 1001)
• 新版本: node 用户 (uid 1000)

即使修正了挂载路径，由于文件权限属于旧用户，新版本仍会报错：

EACCES: permission denied, open '/home/node/.agentx/logs/portagent.log'

复现步骤

1. 使用 portagent:1.3.0 正常运行，创建用户账户
2. 修改 docker-compose.yml 镜像版本为 latest
3. 执行 docker-compose down && docker-compose up -d
4. 发现原有账户数据无法访问

临时解决方案

需要手动执行两步操作：

1. 修改挂载路径：./data:/home/agentx/.agentx → ./data:/home/node/.agentx
2. 修复文件权限：sudo chown -R 1000:1000 ./data

建议改进

为了提供更好的升级体验，建议：

1. 保持向后兼容：继续使用 /home/agentx/.agentx 路径，或通过软链接兼容旧路径
2. 启动时自动迁移：检测旧路径数据并自动迁移到新路径
3. 容器入口脚本处理权限：在 entrypoint 中自动修复数据目录权限
4. 提供升级文档：在 CHANGELOG 或 README 中明确说明破坏性变更和迁移步骤
5. 使用固定 UID/GID：在 Dockerfile 中固定用户 UID，避免权限问题

环境信息

• 旧版本: deepracticexs/portagent:1.3.0
• 新版本: deepracticexs/portagent:latest (2026-01-09)
• 部署方式: docker-compose