Podman 系统连接system connection完全指南远程 Podman 服务的统一管理【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman导读podman system connection是 Podman 内置的远程服务连接管理器用于记录、查看、切换和删除连接到远程或本地Podman 服务的目的地destination。无论你是在管理远端服务器上的 rootful Podman、本机 user 模式下的 Unix 域套接字还是通过 TCP/TLS 暴露的调试服务都可以用这一组命令统一编排并配合--connection全局选项与--remote模式实现无缝的客户端-服务器分离。读完本文你将掌握连接配置的底层存储机制podman-connections.json与containers.conf的service_destinations、全部 5 个子命令的完整用法与参数、可脚本化的--format输出以及源码层面的实现细节从而在日常开发和 CI/CD 环境中高效管理多套 Podman 服务。什么是系统连接System Connectionpodman system connection管理的是Podman service 的目的地destination。Podman 采用客户端/服务器架构客户端CLI通过 SSH、Unix 域套接字或 TCP 连接到运行 Podman 服务的宿主机把命令转发过去执行。每条连接就是一条目的地记录包含协议、主机、端口、Socket 路径以及可选的 SSH 身份文件与 TLS 证书信息。添加连接后你可以通过全局选项--connection name或-c指定使用哪条连接执行任意 Podman 命令例如$ podman --connection production ps $ podman --remote --connection staging images从源码结构看这一命令族由 cmd/podman/system/connection 目录下的 5 个文件实现add.go、default.go、list.go、remove.go、rename.go每个文件对应一个子命令并同时以system connection与 Docker 兼容的system context两条路径注册到命令树中。支持的连接目的地格式podman system connection add接受四种形式的 destination源码中在 add.go 的Long描述里明确列出格式说明[user]hostname简写形式默认按 SSH 处理源码中会补全为ssh://前缀ssh://[user]hostname[:port][/path]SSH 通道/path为远程 Podman 服务 socket 路径未给出时自动探测unix://path本机 Unix 域套接字必须为绝对路径tcp://hostname:port明文 TCP 连接未经 TLS 保护可配合 TLS 参数加密在 add.go 中可以看到若用户输入的目的地不以协议://开头源码会通过正则^[A-Za-z][A-Za-z0-9.-]*://判断后自动补上ssh://前缀因此podman.example.com与ssh://podman.example.com等价。连接配置的存储机制务必理解 ReadWrite 列Podman 管理系统连接时会读写名为podman-connections.json的配置文件。其定位规则如下位于$XDG_CONFIG_HOME/containers目录下若XDG_CONFIG_HOME未设置则默认为$HOME/.config/containers也可以设置环境变量PODMAN_CONNECTIONS_CONF指向一个完整文件路径Podman 将优先使用该文件。重要提醒该文件由 Podman 命令自行管理严禁用户直接手工编辑。如需手动配置连接应使用containers.conf中的service_destinations选项参见 containers.conf 文档仓库根目录下亦有 contrib 配置样例 可供参考。这里引出一个关键概念——ReadWrite 列如果podman system connection list输出中某条连接的ReadWrite 列为true说明该连接存储在可写的podman-connections.json中可以被podman system connection系列命令增删改若为false说明该连接来自containers.conf的service_destinations配置属于只读来源不能通过podman system connection命令编辑。add.go中正是通过config.EditConnectionConfig(func(cfg *config.ConnectionsFile) error {...})回调修改ConnectionsFile结构包含Connection.Connections映射、Connection.Default以及Farm.List农场分组最终落盘到podman-connections.json。命令总览podman system connection提供 5 个子命令完整对应关系如下子命令作用详细手册add记录 Podman 服务的连接目的地podman-system-connection-add(1)default将命名连接设为默认连接podman-system-connection-default(1)list列出全部连接别名lspodman-system-connection-list(1)remove删除命名连接别名rmpodman-system-connection-remove(1)rename重命名连接podman-system-connection-rename(1)通用语法为podman system connection subcommand在使用 SSH 类连接时Podman 会在需要时提示用户输入 SSH 登录密码或密钥文件的 passphrase若本机运行了ssh-agent则会自动使用 agent 中的密钥无需重复输入。添加连接podman system connection add语法与参数podman system connection add [options] NAME DESTINATION其中NAME是连接的自定义名称后续用--connection NAME引用DESTINATION是上文四种格式之一。选项说明默认值--default, -d将新连接同时设为该用户的默认连接false--identitypathSSH 身份文件路径若文件被加密会提示输入 passphrase不提供且未指定用户名时默认使用当前运行 Podman 命令的用户空--port, -pportSSH 目的端口22--socket-pathpathSSH 目的主机上 Podman 服务 Unix 域套接字的路径自动探测/run/podman/podman.sock或/run/user/{uid}/podman/podman.sock--tls-capath用于校验服务端证书的 PEM 格式 CA 证书包路径空--tls-certpath提交给服务端的 PEM 格式 TLS 客户端证书必须同时提供--tls-key空--tls-keypath与--tls-cert匹配的 PEM 格式私钥必须同时提供--tls-cert空上述默认值均可在 add.go 的 flag 注册代码中找到对应实现如flags.IntVarP(cOpts.Port, port, p, 22, ...)。各方案的参数约束源码级校验add.go中针对不同 scheme 做了严格的参数合法性校验值得注意SSHssh://默认方案支持--identity、--port、--socket-path不支持--tls-cert/--tls-key/--tls-ca显式传入会直接报错Unixunix://支持--socket-path不支持--identity源码还会对套接字路径执行os.Stat检查——路径不存在或没有权限时输出警告路径存在但不是 Unix 域套接字时直接报错TCPtcp://支持 TLS 三件套但不支持--socket-path与--identity--tls-cert与--tls-key必须成对出现源码要求Changed(tls-cert) Changed(tls-key)且 TCP 目的地必须显式携带端口通过--port或 URL 中的端口否则报错未知 scheme 仅输出警告不做校验。这些约束确保了配置文件的完整性也解释了为什么 TLS 选项只在tcp://场景下可用。实战示例添加一个命名连接默认走 SSH$ podman system connection add QA podman.example.com指定 SSH 身份文件、用户与端口$ podman system connection add --identity ~/.ssh/dev_rsa production ssh://rootserver.example.com:2222连接本机 Unix 域套接字$ podman system connection add testing unix:///run/podman/podman.sock连接本机 TCP 服务$ podman system connection add debug tcp://localhost:8080自定义 SSH 端口$ podman system connection add --port 2222 staging userstaging.example.com自定义远程 socket 路径例如 user 模式下的套接字$ podman system connection add --socket-path /run/user/1000/podman/podman.sock remote-user userremote.example.com添加并同时设为默认$ podman system connection add --default production rootprod.example.com通过 TLS 加密的 TCP 连接$ podman system connection add secure-debug --tls-certtls.crt --tls-keytls.key --tls-caca.crt tcp://podman.example.com:8443添加连接时若--default未指定且当前没有任何连接源码会在EditConnectionConfig回调中自动将该连接设为默认见 add.go保证始终存在一条可用默认连接。查看连接podman system connection list语法podman system connection list [options] # 别名 podman system connection ls [options]选项选项说明--format, -fformat自定义输出格式支持json或 Go template--quiet, -q仅输出连接名称输出列说明默认表格输出包含Name、URI、Identity、Default、ReadWrite五列。使用--formattls可额外显示 TLS 三列TLSCA、TLSCert、TLSKey。从 list.go 的模板代码可以确认默认模板为{{.Name}}\t{{.URI}}\t{{.Identity}}\t{{.Default}}\t{{.ReadWrite}}tls模板则在其后追加 TLS 三列。Go template 可用占位符占位符说明.Default该连接是否为默认连接.IdentitySSH 身份文件路径.Name连接名称/标识符.ReadWrite该连接是否可用 system connection 命令修改.TLSCAPEM 格式 CA 证书包路径用于校验服务端证书.TLSCertTLS 客户端证书路径.TLSKey与客户端证书匹配的私钥路径.URI指向 Podman 服务的 URI合法 scheme 为ssh://[user]host[:port][Unix域套接字][?secureTrue]、unix://Unix域套接字、tcp://localhost[:port]实战示例列出全部连接$ podman system connection list Name URI Identity Default ReadWrite deva ssh://rootexample.com:/run/podman/podman.sock ~/.ssh/id_rsa true true devb ssh://userexample.com:/run/user/1000/podman/podman.sock ~/.ssh/id_rsa false true输出 JSON 格式便于脚本解析$ podman system connection list --format json [ { Name: podman-machine-default, URI: ssh://core127.0.0.1:53298/run/user/501/podman/podman.sock, Identity: /Users/ragm/.local/share/containers/podman/machine/machine, IsMachine: true, Default: true, ReadWrite: true }, { Name: podman-machine-default-root, URI: ssh://root127.0.0.1:53298/run/podman/podman.sock, Identity: /Users/ragm/.local/share/containers/podman/machine/machine, IsMachine: true, Default: false, ReadWrite: true } ]说明JSON 输出中额外包含IsMachine字段用于标识由podman machine创建的虚拟机连接该字段已在 list.go 的config.Connection结构中承载。仅显示名称与 URI$ podman system connection list --format {{.Name}}\t{{.URI}} podman-machine-default ssh://core127.0.0.1:53298/run/user/501/podman/podman.sock podman-machine-default-root ssh://root127.0.0.1:53298/run/podman/podman.sock以多行格式输出全部明细适合审计与排障$ podman system connection list --format Name: {{.Name}}\nURI: {{.URI}}\nIdentity: {{.Identity}}\nDefault: {{.Default}}\nReadWrite: {{.ReadWrite}}\n--- Name: podman-machine-default URI: ssh://core127.0.0.1:53298/run/user/501/podman/podman.sock Identity: /Users/ragm/.local/share/containers/podman/machine/machine Default: true ReadWrite: true --- Name: podman-machine-default-root URI: ssh://root127.0.0.1:53298/run/podman/podman.sock Identity: /Users/ragm/.local/share/containers/podman/machine/machine Default: false ReadWrite: true ---从源码实现看list与 Docker 兼容的context inspect共用同一个inspect函数见 list.go数据通过registry.PodmanConfig().ContainersConfDefaultsRO.GetAllConnections()汇总读取按名称排序后交给 report 模块渲染支持json、tls、用户自定义模板三种输出路径。若指定--quiet则直接逐行打印名称并提前返回。设置默认连接podman system connection defaultpodman system connection default NAME将指定的命名 SSH 目的地设置为 Podman 服务的默认目的地。设置后不带--connection的远程命令将默认路由到该连接。$ podman system connection default production结合add --default与default子命令可以灵活地在多套环境开发/预发/生产之间切换默认目标而无需每次命令都显式指定连接名。删除连接podman system connection removepodman system connection remove [options] NAME # 别名 podman system connection rm NAME选项说明--all, -a删除全部连接示例——删除单条连接$ podman system connection remove production删除全部连接$ podman system connection remove --all从 remove.go 的实现看删除逻辑比表面更细致删除指定连接后若它恰好是默认连接会把Default置空cfg.Connection.Default --all会清空全部连接与默认值农场farm联动无论单删还是全删都会同步从Farm.List中移除对应连接全删时清空所有农场成员列表避免遗留指向已删除连接的农场引用。这也提醒使用者连接被删除后依赖它的 farm 配置会自动同步清理。重命名连接podman system connection renamepodman system connection rename OLD NEW将连接从旧名称重命名为新名称$ podman system connection rename laptop devel重命名常用于环境交接或命名规范调整例如把以人名命名的laptop规范化为按用途命名的devel。源码实现要点与工作流小结综合以上源码cmd/podman/system/connection 目录可以梳理出这一命令族的整体工作流解析add对 destination 字符串做 scheme 归一化缺省补ssh://与url.Parse解析校验按 scheme 分支执行差异化参数校验TLS 仅限tcp://、identity 不适用于unix:///tcp://等落盘所有写操作add/remove/rename统一经由config.EditConnectionConfig回调修改ConnectionsFile结构最终写入podman-connections.json读取list通过GetAllConnections()合并读取可写文件与containers.conf的service_destinations前者标记ReadWritetrue后者标记ReadWritefalse联动对 farmPodman 农场多机批量执行的增删同步维护避免数据不一致。整个podman system connection家族同时注册为 Docker 兼容的podman system context子命令create/list/inspect/remove便于从 Docker Context 迁移的用户无缝过渡。常见问题与注意事项配置文件被误改podman-connections.json由命令维护手工编辑可能导致格式错误或连接丢失需要静态配置时请使用containers.conf的service_destinations这类连接会以ReadWritefalse呈现且不可被命令修改。SSH 密码/密钥提示Podman 会按需提示登录密码或密钥 passphrase启用ssh-agent可免去重复输入。若连接指向远程 rootful Podman通常需要 root 用户或 sudo 权限访问/run/podman/podman.sock。TCP 连接的安全tcp://明文传输生产环境务必搭配--tls-ca/--tls-cert/--tls-key使用且三者的校验约束cert 与 key 必须成对由 add.go 强制保证。查看只读连接的来源当某连接ReadWritefalse时不要尝试用remove/rename修改请直接编辑containers.conf的service_destinations。延伸阅读podman(1)全局选项--connection/--remote的完整说明podman-system(1)system命令族总览podman-system-connection-add(1)、podman-system-connection-list(1)、podman-system-connection-default(1)、podman-system-connection-remove(1)、podman-system-connection-rename(1)各子命令独立手册containers.conf(5)service_destinations静态配置语法源码入口cmd/podman/system/connectionadd.go / list.go / remove.go / default.go / rename.go【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考