如何快速部署 HolyClaude：无根 Podman 与 SELinux 的 keep-id 和 :Z 标签权限完全指南
【免费下载链接】HolyClaudeAI coding workstation: Claude Code + web UI + 8 AI CLIs + headless browser + 50+ tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude
HolyClaude是一台可自托管的 AI 编程工作站，内置 Claude Code、Web UI、多个 AI CLI 与无头浏览器。本文面向 Fedora 等启用 SELinux 的主机，手把手讲解如何在**无根 Podman（rootless Podman）**上部署 HolyClaude，重点讲透keep-id用户命名空间映射与:Z卷标签两大权限机制，帮你一次解决"容器内写的文件宿主机改不了"的顽疾 🛠️
为什么无根 Podman 需要单独配置？
Docker 里设置PUID=1000后，容器内进程就是 UID 1000。但无根 Podman 没有 root 权限，它默认把容器内 UID 映射到你/etc/subuid、/etc/subgid里的从属 UID 范围（比如 100000+）。结果就是：
- 容器以为自己在写 UID 1000 的文件；
- 宿主机看到的却是
100000之类的"陌生用户"，SELinux 还会额外拦一道。
于是git、npm install动不动就Permission denied。HolyClaude 专门为此提供了一份 docker-compose.podman-rootless.yaml，两个机制各司其职：
| 机制 | 解决的问题 |
|---|---|
userns_mode: "keep-id:uid=1000,gid=1000" | 让容器内 UID 1000 在宿主机上真实可见，文件归属与你的宿主用户一致 |
卷挂载加:Z标签 | SELinux 自动重标记挂载目录，容器与宿主机都能读写 |
💡 一句话记忆：
keep-id管"是谁的文件"，:Z管"SELinux 让不让访问"。
一键安装步骤：三条命令完成部署
先克隆仓库获取配置文件：
git clone https://gitcode.com/gh_mirrors/ho/HolyClaude cd HolyClaude按官方文档（见 README.md）的无根 Podman 部署章节执行：
# 第一步：创建持久化目录 mkdir -p data/claude data/cloudcli workspace # 第二步：启动无根 Podman 专用配置 podman compose -f docker-compose.podman-rootless.yaml up -d # 第三步：浏览器打开 # http://localhost:3001核心配置都在 docker-compose.podman-rootless.yaml 中，关键几行：
userns_mode: "keep-id:uid=1000,gid=1000" volumes: - ./data/claude:/home/claude/.claude:Z - ./data/cloudcli:/home/claude/.cloudcli:Z - ./workspace:/workspace:Z environment: - PUID=1000 - PGID=1000如果你的宿主用户不是 UID/GID 1000，请先id -u和id -g确认，并同步修改keep-id与PUID/PGID三处。
keep-id 映射机制详解：为什么 PUID 不够用
keep-id是 Podman 4.0 引入的用户命名空间模式。它只建立一条恒等映射：容器内 UID 1000 ↔ 宿主机 UID 1000，其余 UID 再走从属范围。效果是：
- 容器内创建的文件，宿主机
ls -l直接显示为你的用户名； - 宿主机上编辑的代码，容器内同样有读权限；
- 不需要 root 权限就能实现 Docker 用户重映射的体验。
这也是为什么官方文档反复强调：无根 Podman 用户请改用 Podman 配置文件，不要只靠PUID/PGID（详见 docs/configuration.md 的 Rootless Podman 一节）。HolyClaude 的启动脚本 scripts/entrypoint.sh 也做了适配——检测不到 root 时会自动跳过 root-only 的修复动作，直接以目标用户运行。
:Z 标签详解：SELinux 下的正确姿势
SELinux 主机上，光 UID 对还不行，文件还得带正确的SELinux 标签。Podman 的卷标签后缀就是干这个的：
| 后缀 | 行为 | 建议 |
|---|---|---|
:Z | 把目录私有重标记为容器标签，每次挂载自动对齐 | ✅ 本方案使用 |
:U | 递归重写宿主机文件属主为容器命名空间用户 | ❌ 官方明确不建议 |
README.md 中的 Permissions 章节特别提醒：不要给/workspace加:U——它会递归改写宿主机文件归属，反而让宿主机编辑失败。:Z只动标签、不动属主，宿主机和容器双向编辑./workspace才能同时成立。
⚠️ 另外两条避坑提示（来自 docs/troubleshooting.md）：
- CloudCLI 的 SQLite 数据库（
./data/cloudcli）请留在本地磁盘，不要放到 NAS/SMB/NFS 上； - 无根 Podman不会做 Docker 那种特权属主修复，所以别试图用
chown -R修目录，权限应由keep-id+:Z保证。
最快验证方法：30 秒确认配置生效
部署完成后，运行以下两条验证命令（与 tests/docker_rootless_smoke.sh 的冒烟检查思路一致）：
# 验证容器内就是 UID 1000 podman exec holyclaude id # 验证双向可写：容器内建的文件，宿主机属主正确 podman exec holyclaude sh -c 'printf ok > /workspace/rootless-test.txt' ls -l workspace/rootless-test.txt # 应显示为你的用户若id显示的不是uid=1000 gid=1000，说明keep-id参数没写对；若宿主机ls显示属主异常，通常是 UID 不匹配，回到"一键安装步骤"对齐三处数值即可。
常见问题速查
| 症状 | 原因与修复 |
|---|---|
Permission denied/ git 失败 | 改用 docker-compose.podman-rootless.yaml；确认keep-id的 UID 与宿主用户一致 |
unable to open database file | .cloudcli目录不可写，检查:Z是否遗漏、是否误用:U |
| 容器内写成功但宿主机属主怪异 | 典型 subuid 映射问题，必须上keep-id |
SELinuxPermission denied但 UID 正确 | 标签问题，确认三个卷都带:Z |
更多排障场景（Chromium 崩溃、文件监听、NAS 挂载等）可查阅 docs/troubleshooting.md；完整配置项清单见 docs/configuration.md。
总结：记住这张清单
- ✅ 用 docker-compose.podman-rootless.yaml，别用普通 Docker 配置；
- ✅
keep-id:uid=<你的UID>,gid=<你的GID>解决"文件是谁的"； - ✅ 三个卷全部带
:Z解决"SELinux 让不让访问"； - ❌ 不给
/workspace加:U，它重写属主后适得其反； - ❌ SQLite 状态不进网络存储。
掌握keep-id与:Z这对组合拳，你就能在 Fedora、RHEL 等 SELinux 主机上，以完全无 root 的方式获得一台文件权限"无感"的 HolyClaude AI 编程工作站。祝部署顺利 🚀
【免费下载链接】HolyClaudeAI coding workstation: Claude Code + web UI + 8 AI CLIs + headless browser + 50+ tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
