一、核心概念与作用
在 Hermes-WebUI 部署中，UID/GID 配置的核心目的是解决容器与宿主机文件权限不匹配问题，避免出现 Permission denied 错误，确保容器内进程能正常读写挂载的宿主机目录（如 ~/.hermes 和 ~/workspace）。
二、设置方法（保姆级步骤）
1. 操作时机（关键！）
必须在首次启动容器前完成，建议作为部署的第一步操作。若已启动过容器并出现权限问题，需先停止容器、删除相关卷，重新配置后再启动。
2. 创建 .env 文件（推荐方式）
在项目根目录执行以下命令，自动获取当前用户的 UID/GID 并写入 .env 文件：
# 创建 .env 文件并写入宿主机 UID/GID
echo "UID=$(id -u)" >> .env
echo "GID=$(id -g)" >> .env
# 为 hermes-agent 和 hermes-dashboard 配置相同的 UID/GID
echo "HERMES_UID=$(id -u)" >> .env
echo "HERMES_GID=$(id -g)" >> .env
# 为 hermes-webui 明确配置 WANTED_UID/WANTED_GID（推荐）
echo "WANTED_UID=$(id -u)" >> .env
echo "WANTED_GID=$(id -g)" >> .env
3. 验证配置
查看 .env 文件确认配置正确：
cat .env
预期输出（示例，数字会因用户不同而变化）：
UID=1000
GID=1000
HERMES_UID=1000
HERMES_GID=1000
WANTED_UID=1000
WANTED_GID=1000
4. 特殊场景配置
三、配置生效方式
1. Docker Compose 部署（推荐）
在 docker-compose.yml 中引用 .env 文件变量：
yaml
services:
hermes-webui:
image: ghcr.io/nesquena/hermes-webui:latest
environment:
- WANTED_UID=${WANTED_UID:-1000} # 优先使用 .env 中的值，默认 1000
- WANTED_GID=${WANTED_GID:-1000}
volumes:
- ~/.hermes:/opt/data
- ~/workspace:/workspace
hermes-agent:
image: nousresearch/hermes-agent:latest
environment:
- HERMES_UID=${HERMES_UID:-1000}
- HERMES_GID=${HERMES_GID:-1000}
volumes:
- ~/.hermes:/opt/data
2. 单容器运行
直接通过 -e 参数传递环境变量：
docker run -d \
-e WANTED_UID=$(id -u) \
-e WANTED_GID=$(id -g) \
-v ~/.hermes:/opt/data \
-v ~/workspace:/workspace \
-p 8080:8080 \
ghcr.io/nesquena/hermes-webui:latest
四、权限问题排查与修复
1. 已存在的～/.hermes 目录权限修复
若之前未配置正确 UID/GID 导致权限问题，执行以下命令修复：
# 停止并删除容器
docker compose down
# 修复宿主机目录权限（使用你配置的 UID/GID）
sudo chown -R $(id -u):$(id -g) ~/.hermes
# 重新启动容器
docker compose up -d
2. 自动检测机制说明
最新版本（v0.50.69+）WebUI 支持从
/workspace目录自动检测 UID/GID显式在 .env 文件中设置
WANTED_UID/WANTED_GID始终优先于自动检测双容器 / 三容器共享卷场景，WebUI 会从共享 hermes-home 卷自动检测正确 UID/GID
五、总结
操作时机：首次部署前创建 .env 文件配置 UID/GID，这是避免权限问题的关键一步
配置方法：使用
id -u和id -g命令获取当前用户 UID/GID，写入 .env 文件核心原则：所有共享同一挂载目录的容器（WebUI、Agent、Dashboard）必须使用相同 UID/GID
特殊情况：macOS 和 NAS 用户需特别注意 UID/GID 配置，避免默认值导致的权限错误
完成以上配置后，即可正常启动 Hermes-WebUI 容器，享受无权限问题的 AI 代理体验！