【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载本文是 OpenShell Gateway 在 Fedora / RHEL 系统上通过 RPM 包安装后的配置参考指南覆盖默认配置模板与种子机制、三类自定义配置入口、默认启用的 mTLS 证书体系自动生成、外部证书、轮换与禁用、沙箱容器回连网关的 guest TLS 挂载、Gateway 与 Podman 驱动完整配置项、镜像拉取策略与离线部署以及 schema v2 升级迁移要点。读完本文你将掌握如何在 RPM 部署形态下安全地定制网关、管理证书与容器镜像并理解各配置项在源码层面的实际作用。配置模型总览模板、种子与优先级RPM 包随附一份只读的 TOML 配置模板位于/usr/share/openshell-gateway/gateway.toml.default。首次启动openshell-gateway.service时systemd 用户单元会把它复制为活动配置文件~/.config/openshell/gateway.toml仅当该文件尚不存在时。这份模板默认针对 rootless Podman 使用场景调优[openshell] version 2 [openshell.gateway] compute_driver podman仓库中的真实模板见 deploy/rpm/gateway.toml.default它额外保留了[openshell.drivers.podman]下的health_check_interval_secs 10目的是在 Podman 驱动的健康检查改为 opt-in 之后保持打包默认的本地网关就绪行为。模板头部注释明确给出了配置优先级CLI flag OPENSHELL_*环境变量 TOML 文件 内置默认值RPM 不覆盖绑定地址的用意RPM 包不覆盖bind_address。主监听器沿用内置默认127.0.0.1:17670host 网络模式的 Podman supervisor 会话复用同一个 loopback 监听器因此网关不会额外暴露主机网卡接口。在 openshell-server 的 CLI 定义中bind_address的 clap 默认值就是127.0.0.1端口默认值来自DEFAULT_SERVER_PORT即文档所述的 17670且均支持OPENSHELL_BIND_ADDRESS/OPENSHELL_SERVER_PORT环境变量覆盖。为什么必须 pin compute_drivercompute_driver podman把计算驱动固定为 Podman。若不设置网关会按Kubernetes → Podman → Docker的顺序自动检测。固定驱动可以防止主机同时装有 Docker 时被意外选中。从 openshell-gateway 的驱动注册源码可以看到内置驱动的注册优先级为Kubernetes 为100、Podman 为200、Docker 为300数字越小越优先同时 Podman 驱动带is_available探测函数这正对应文档所述自动检测顺序。另外schema v2 下 legacy 的compute_drivers列表写法会被拒绝。自定义配置的三种方式方式一直接编辑活动 TOML推荐编辑~/.config/openshell/gateway.toml。注意包所有的模板/usr/share/openshell-gateway/gateway.toml.default运行时不会被读取且可能在 RPM 升级时被更新活动用户副本则会被保留。在 schema-v2 升级过程中服务只替换可识别的、由包生成的 v1 副本从不重写用户编辑过的配置判断依据是内容与 v1 种子完全一致见下文迁移小节。在生成证书或启动网关前服务会对生效配置执行openshell-gateway config preflight校验失败即停止启动。方式二gateway.env 环境变量覆盖需要跨升级持久生效、又不想改 TOML 的环境变量覆盖可写入~/.config/openshell/gateway.env。systemd 用户单元通过EnvironmentFile在每次启动时读取该文件RPM/Deb 单元中写法为EnvironmentFile-.../gateway.env见 deploy/deb/openshell-gateway.service# 示例在主监听器上显式暴露一个主机网卡接口 OPENSHELL_BIND_ADDRESS192.168.1.10完全替换 TOML 配置文件路径# 仍在 ~/.config/openshell/gateway.env 中 OPENSHELL_GATEWAY_CONFIG/path/to/custom/gateway.tomlOPENSHELL_GATEWAY_CONFIG正是 CLI 定义中--config参数的环境变量别名。方式三systemd drop-in 覆盖一次性服务级覆盖且跨包升级保留systemctl --user edit openshell-gateway生成的 drop-in 可放置Environment行如OPENSHELL_LOG_LEVELdebug或直接覆盖ExecStart参数。这三条路径加上内置默认值共同构成CLI flag env TOML built-in的完整优先级链。默认 mTLS自动生成证书体系RPM 部署默认启用双向 TLSmTLS网关要求所有 API 连接携带有效客户端证书。主监听器使用127.0.0.1:17670Podman supervisor 会话复用同一监听器。首次启动自动生成首次启动时systemd 用户单元执行openshell-gateway generate-certs --output-dir ~/.local/state/openshell/tls --server-san host.openshell.internal该命令使用rcgen生成证书与 CLI 生成本地 mTLS bundle 时同一套例程。单元将OPENSHELL_LOCAL_TLS_DIR设为该路径证书生成与网关启动使用同一值。要使用自定义 bundle 位置可在~/.config/openshell/gateway.env中预先设置OPENSHELL_LOCAL_TLS_DIR再启动服务。系统生成的证书文件如下文件用途位置CA certificate信任根~/.local/state/openshell/tls/ca.crtCA private key签发服务器与客户端证书~/.local/state/openshell/tls/ca.keyServer certificate网关 TLS 身份~/.local/state/openshell/tls/server/tls.crtServer private key网关 TLS 私钥~/.local/state/openshell/tls/server/tls.keyClient certificateCLI 与沙箱身份~/.local/state/openshell/tls/client/tls.crtClient private keyCLI 与沙箱私钥~/.local/state/openshell/tls/client/tls.key客户端证书同时复制到 CLI 自动发现目录~/.config/openshell/gateways/openshell/mtls/ ca.crt tls.crt tls.keyCLI 在连接localhost或127.0.0.1上的网关时会自动发现这些证书。服务器证书 SAN 列表自动生成的服务器证书包含以下 Subject Alternative Nameslocalhostopenshellopenshell.openshell.svcopenshell.openshell.svc.cluster.localhost.containers.internalhost.docker.internalhost.openshell.internal127.0.0.1要从远程机器连接需要额外 SAN 的外部托管证书详见 TROUBLESHOOTING.md 的 Remote CLI access 一节。使用外部托管证书外部 CA 或 cert-manager将服务器证书、私钥和 CA 证书放到文件系统上。编辑~/.config/openshell/gateway.toml[openshell.gateway.tls] cert_path /path/to/server/tls.crt key_path /path/to/server/tls.key client_ca_path /path/to/ca.crt将客户端证书放到 CLI 预期位置~/.config/openshell/gateways/openshell/mtls/ ca.crt tls.crt tls.key轮换证书删除 TLS 状态目录并重启网关rm -rf ~/.local/state/openshell/tls systemctl --user restart openshell-gateway网关会在下次启动时重新生成整套 PKI。若证书损坏导致启动失败这也是 TROUBLESHOOTING 推荐的恢复手段。禁用 TLS不推荐用于生产WARNING:TLS 禁用后网关 API 没有任何认证。请保持绑定地址为127.0.0.1或将网关置于自行实施认证的 TLS 终止反向代理之后。编辑~/.config/openshell/gateway.toml[openshell.gateway] disable_tls true若已设置guest_tls_*条目请在~/.config/openshell/gateway.toml中移除或注释掉。重启网关。注意mTLS 一旦启用本地计算驱动Docker/Podman/VM必须提供完整的 guest TLS bundle否则网关启动直接失败详见下节。Sandbox 容器回连guest TLS 挂载启用 mTLS 时Podman 驱动会把客户端证书 bind-mount 进每个沙箱容器使 supervisor 进程能向网关建立 mTLS 回连连接。以下 TOML 字段控制挂载进沙箱容器的客户端证书的主机侧路径[openshell.gateway] guest_tls_ca /home/user/.local/state/openshell/tls/ca.crt guest_tls_cert /home/user/.local/state/openshell/tls/client/tls.crt guest_tls_key /home/user/.local/state/openshell/tls/client/tls.key容器内 supervisor 从以下位置读取/etc/openshell/tls/client/ca.crt/etc/openshell/tls/client/tls.crt/etc/openshell/tls/client/tls.key在 SELinux 启用系统上Podman 驱动会自动为这些 bind mount 附加:zrelabel 选项无需手动 SELinux 配置TROUBLESHOOTING 的 SELinux 一节也确认了这点。源码层的强制校验逻辑从 openshell-gateway 的本地驱动 TLS 校验实现可以看到两个关键行为validate_local_driver_guest_tls当gateway_tls_enabled !has_guest_tls时直接返回配置错误——gateway TLS requires guest_tls_ca, guest_tls_cert, and guest_tls_key in [openshell.gateway]。这正是文档所说网关在启动时失败而不是让沙箱稍后失败的实现依据。apply_guest_tls当三个guest_tls_*字段都未配置时注入包管理 bundleOPENSHELL_LOCAL_TLS_DIR下的默认路径一旦用户显式配置了其中任一字段则以用户配置为准不再注入默认值。对应的单元测试tls_enabled_local_drivers_require_a_guest_bundle、package_managed_guest_bundle_is_injected_when_driver_paths_are_absent验证了这两种分支。在 Podman 驱动配置中当三个 TLS 路径全部设置时驱动会把挂载进容器的自动检测回连端点从http://切换为https://。配置参考Gateway 与 Driver 设置网关与驱动设置都带本地运行时默认值。网关存在~/.config/openshell/gateway.toml时读取之在启动环境中设置OPENSHELL_GATEWAY_CONFIG可使用其他文件。跨包升级持久生效的服务环境覆盖使用systemctl --user edit openshell-gateway。从旧版本升级参见 TROUBLESHOOTING.md 的 Migrating from gateway.env 一节其中有 env-to-TOML 映射表以及默认端口、绑定地址、数据库路径变更的说明。Gateway 设置表TOML optionDefaultDescriptionbind_address127.0.0.1:17670网关默认主 gRPC/HTTP API 监听器地址。compute_driverpodmanRPM 默认未设置时网关自动检测 Kubernetes → Podman → Docker。RPM 默认固定为 Podmanlegacycompute_drivers列表会被拒绝。[openshell.drivers.podman].default_imagenvcr.io/nvidia/base/ubuntu:24.04默认沙箱镜像。[openshell.drivers.podman].sandbox_runtime_imageghcr.io/nvidia/openshell/sandbox:latest静态链接 musl 沙箱运行时镜像挂载进 Podman 工作负载。[openshell.drivers.podman].supervisor_imageghcr.io/nvidia/openshell/supervisor:latest动态链接 glibc supervisor 镜像在工作负载外运行。[openshell.gateway].guest_tls_ca、guest_tls_cert、guest_tls_key自动生成路径网关持有的客户端 TLS 材料注入所选本地驱动并挂载进沙箱容器。[openshell.gateway.tls]路径自动生成路径服务器 TLS 证书、私钥与客户端 CA。disable_tls未设置设为true以禁用 TLS。数据库 URL不接受写在 TOML 中。当OPENSHELL_DB_URL未设置时网关使用sqlite:$XDG_STATE_HOME/openshell/gateway/openshell.db。Driver TOML 设置示例需要定制驱动设置时创建~/.config/openshell/gateway.toml[openshell] version 2 [openshell.gateway] compute_driver podman [openshell.drivers.podman] network_name openshell default_image nvcr.io/nvidia/base/ubuntu:24.04 image_pull_policy if_not_present health_check_interval_secs 10 stop_timeout_secs 10对照 PodmanComputeConfig 结构体可以进一步理解这些字段的语义network_name驱动管理资源使用的 Podman bridge 网络名。image_pull_policy合法取值always/missing即 if_not_present/never/newer由podman_image_pull_policy映射到 Podman 原生策略。health_check_interval_secssupervisor 容器健康检查间隔。该字段为OptionNonZeroU64省略即完全禁用健康检查显式填 0 非法。文档与模板中的 10 秒是为保持旧版就绪行为而设置的打包默认间隔越小就绪检测越快但每次检查都会 spawn conmon 子进程进程抖动越大。stop_timeout_secs容器停止超时SIGTERM → SIGKILL。sandbox_runtime_image与supervisor_image在代码注释中说明了二者差异运行时镜像含静态链接的openshell-sandbox二进制驱动从镜像中提取二进制、放入经校验的主机缓存并只读挂载进沙箱supervisor 镜像则含动态链接的openshell-supervisor二进制。镜像管理与离线部署网关在首次创建沙箱时自动拉取容器镜像。默认拉取策略为if_not_present镜像只拉取一次之后由 Podman 缓存。更新缓存的镜像podman pull ghcr.io/nvidia/openshell/supervisor:latest podman pull nvcr.io/nvidia/base/ubuntu:24.04或在[openshell.drivers.podman]中设置image_pull_policy always让每次创建沙箱都重新拉取。固定镜像版本要固定具体版本而非:latest在[openshell.drivers.podman]中设置sandbox_runtime_image ghcr.io/nvidia/openshell/sandbox:v0.0.37 supervisor_image ghcr.io/nvidia/openshell/supervisor:v0.0.37 default_image nvcr.io/nvidia/base/ubuntu:24.04离线air-gapped环境在联网机器上拉取并保存镜像podman pull ghcr.io/nvidia/openshell/supervisor:latest podman pull nvcr.io/nvidia/base/ubuntu:24.04 podman save -o supervisor.tar ghcr.io/nvidia/openshell/supervisor:latest podman save -o sandbox.tar nvcr.io/nvidia/base/ubuntu:24.04将 tarball 传输到离线主机并加载podman load -i supervisor.tar podman load -i sandbox.tar将拉取策略设为never[openshell.drivers.podman] image_pull_policy never注意离线主机的连通性前提是能访问 ghcr.ioHTTPS 443 端口否则首次创建沙箱会因拉取失败而报错。文件位置速查表用途路径网关二进制/usr/bin/openshell-gatewayCLI 二进制/usr/bin/openshellsystemd 用户单元/usr/lib/systemd/user/openshell-gateway.service默认 TOML 配置模板只读/usr/share/openshell-gateway/gateway.toml.default活动网关 TOML 配置~/.config/openshell/gateway.toml可选环境变量覆盖~/.config/openshell/gateway.envTLS 证书~/.local/state/openshell/tls/CLI 客户端证书~/.config/openshell/gateways/openshell/mtls/网关数据库~/.local/state/openshell/gateway/openshell.db升级与迁移要点schema v1 → v2 的配置文件迁移RPM 的 v1 模板gateway.toml.default.v1使用version 1与compute_drivers [podman]列表写法v2 模板gateway.toml.default改为version 2与标量compute_driver podman。仓库中的 migrate-gateway-config.sh 实现了升级时的替换策略目标文件不存在 → 直接以 v2 默认模板种子化目标文件存在但与 v1 种子逐字节一致cmp -s→ 替换为 v2 模板目标文件存在且被编辑过哪怕只改过空白或注释→不替换操作者拥有的文件保持权威源或目标为符号链接/非常规文件时拒绝操作。这正是服务只替换包生成的 v1 副本、从不重写编辑过的配置的脚本级实现。TROUBLESHOOTING 提醒直接dnf/rpm升级不走install.sh的 breaking-upgrade guard若你的 v1 文件已编辑需在重启服务前手动迁移字段。从 gateway.env 迁移到 TOML旧版本首次启动会生成~/.config/openshell/gateway.env并在启动时用它配置网关新版本从内置运行时默认值启动仅在文件存在时读取~/.config/openshell/gateway.toml。若你仍有gateway.env它仍会被 systemd 的EnvironmentFile在每次启动时读取可以保留或删除新安装不再生成它。迁移映射表环境变量TOML 等价项OPENSHELL_BIND_ADDRESSAOPENSHELL_SERVER_PORTP[openshell.gateway]下bind_address A:POPENSHELL_COMPUTE_DRIVERpodman[openshell.gateway]下compute_driver podmanOPENSHELL_DISABLE_TLStrue[openshell.gateway]下disable_tls trueOPENSHELL_TLS_CERTPATH[openshell.gateway.tls]下cert_path PATHOPENSHELL_TLS_KEYPATH[openshell.gateway.tls]下key_path PATHOPENSHELL_TLS_CLIENT_CAPATH[openshell.gateway.tls]下client_ca_path PATHOPENSHELL_DB_URLURL仅环境变量——不写进 TOML保留在 env 或 drop-in 覆盖中OPENSHELL_LOG_LEVELdebug仅环境变量——以EnvironmentOPENSHELL_LOG_LEVELdebug放在 drop-in 中其他破坏性变更默认端口从 8080 改为 17670若曾在https://127.0.0.1:8080注册网关需重新注册openshell gateway add --local https://127.0.0.1:17670。默认绑定地址从0.0.0.0改为127.0.0.1如需网络访问在 TOML 中显式绑定可达网卡例如bind_address 192.168.1.10:17670并相应更新 firewalld 规则移除 8080/tcp、添加 17670/tcp。数据库路径变更由~/.local/state/openshell/gateway.db改为~/.local/state/openshell/gateway/openshell.db。既有网关状态已注册沙箱等不会自动迁移可在重启前手动搬移mkdir -p ~/.local/state/openshell/gateway mv ~/.local/state/openshell/gateway.db \ ~/.local/state/openshell/gateway/openshell.db迁移 TLS 启用的本地驱动到 schema v2Docker、Podman、VM 沙箱回连网关时使用 guest TLS bundle。包管理安装使用~/.local/state/openshell/tls下生成的完整 bundle因此 RPM 默认无需额外 TOML。如果你用自定义--tls-cert/--tls-key覆盖了监听器且未使用该托管 bundle则必须在[openshell.gateway]下配置全部三个guest_tls_ca、guest_tls_cert、guest_tls_key路径网关现在会在启动时失败而不是让沙箱稍后失败。TLS 禁用时则应省略全部三个字段。相关文档首次部署见 deploy/rpm/QUICKSTART.md含 rootless Podman 前置条件、linger 持久化、首个沙箱创建。故障排查、远程 CLI 访问、升级流程见 deploy/rpm/TROUBLESHOOTING.md。模板与迁移脚本deploy/rpm/gateway.toml.default、deploy/rpm/gateway.toml.default.v1、deploy/rpm/migrate-gateway-config.sh。systemd 用户单元参考deploy/deb/openshell-gateway.serviceExecStartPre的 preflight 与 generate-certs 逻辑与 RPM 一致。赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐Podman 健康检查间隔--health-interval / HealthInterval完全指南默认值、disable 语义与覆盖镜像配置Podman 健康检查间隔 health interval / HealthInterval完全指南默认值、disable 语义与覆盖镜像配置 本篇技术指容器运行时云原生CLIEnvoy Proxy Gateway 后端 mTLS 配置实战指南Envoy Proxy Gateway 后端 mTLS 配置实战指南 前言 在现代微服务架构中服务间的安全通信至关重要。Envoy Proxy GatewayAPI网关后端云原生微服务Envoy Gateway Helm安装与配置完全指南Envoy Gateway Helm安装与配置完全指南 前言 Envoy Gateway作为云原生环境下的高性能API网关解决方案提供了基于KuberneteAPI网关后端云原生微服务上一篇如何永久保存你的数字记忆WeChatMsg年度报告生成器完整指南下一篇免费解锁IDM下载加速的终极方案告别试用期限制的智能脚本指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考