Podman 部署 guacd 容器问题排查与解决笔记

环境信息

系统架构: aarch64 (ARM64)
内核版本: Linux 6.1.31-sun50iw9
容器工具: Podman
目标镜像: docker.io/linuxserver/guacd:latest
网络: 自定义外部网络 znet

问题现象

进入容器后检查端口，发现没有 4822 端口监听，guacd 服务未启动。

检查命令及输出:

netstat -tuln
# 只显示表头，没有监听端口

ss -tuln
# /bin/sh: ss: not found

ps aux
# 只有 s6 进程管理器和基础系统，没有 guacd 进程

排查过程

步骤1: 检查 guacd 是否存在

which guacd
# 无输出

find / -name guacd 2>/dev/null
# 无输出

guacd -f -b 0.0.0.0 -p 4822
# bash: guacd: command not found

结论: 容器内根本没有安装 guacd 二进制文件。

步骤2: 检查系统类型和包管理器

cat /etc/os-release
# cat: /etc/os-release: No such file or directory

uname -a
# Linux 7c0df88ff88a 6.1.31-sun50iw9 #1.0.4 SMP Thu Jul 11 16:37:41 CST 2024 aarch64 GNU/Linux

which apk
# /sbin/apk

apk --version
# apk-tools 2.12.7, compiled for aarch64.

结论: 系统为 Alpine Linux，有 apk 包管理器。

步骤3: 检查 s6 服务配置

ls -la /etc/services.d/
# 目录为空

ls -la /etc/services.d/guacd/
# No such file or directory

结论: linuxserver/guacd 镜像的 s6 服务配置缺失，没有自动启动 guacd 的脚本。

步骤4: 检查容器镜像配置

podman inspect 0cbc473ccde3
# 显示使用 docker.io/linuxserver/guacd:latest 镜像
# 镜像构建时间: 2023-02-15

步骤5: 检查 docker-compose.yml 配置

原始配置:

services:
  guacd:
    image: docker.io/linuxserver/guacd:latest
    container_name: guacd
    restart: on-failure
    environment:
      LOG_LEVEL: error
      TZ: Asia/Shanghai
    deploy:
      resources:
        limits:
          memory: 300M
    networks:
      - znet
    security_opt:
      - no-new-privileges:true

问题: 配置中没有指定平台架构，且使用的 linuxserver 镜像可能不完整。

步骤6: 重新部署时发现架构警告

podman-compose up -d
# WARNING: image platform ({amd64 linux  [] }) does not match the expected platform ({arm64 linux  [] })

结论: 拉取的是 amd64 架构的镜像，与宿主机的 arm64 架构不匹配。

步骤7: 验证官方镜像对 ARM64 的支持

podman manifest inspect docker.io/guacamole/guacd:1.6.0 | grep -E "architecture|os"
# "architecture": "amd64",
# "architecture": "arm64",
# "architecture": "unknown",

结论: 官方镜像正式支持 ARM64 架构。

解决方案

最终 docker-compose.yml 配置

services:
  guacd:
    image: docker.io/guacamole/guacd:1.6.0
    container_name: guacd
    platform: linux/arm64
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
    deploy:
      resources:
        limits:
          memory: 300M
    networks:
      - znet
    security_opt:
      - no-new-privileges:true

networks:
  znet:
    external: true

部署步骤

停止并删除旧容器
```
podman-compose down
podman rm guacd
```

删除错误架构的镜像

podman rmi docker.io/guacamole/guacd:latest

拉取正确架构的镜像

podman pull --platform linux/arm64 docker.io/guacamole/guacd:1.6.0

重新启动服务
```
podman-compose up -d
```

验证结果

podman exec -it guacd /bin/sh

# 检查端口监听
netstat -tuln
# tcp        0      0 0.0.0.0:4822            0.0.0.0:*               LISTEN

# 检查进程
ps aux
# PID   USER     TIME  COMMAND
#     1 guacd     0:00 /opt/guacamole/sbin/guacd -f -b 0.0.0.0 -L error

关键知识点

容器内无端口监听的原因:
- 服务未安装
- 服务已安装但未启动
- 服务启动但监听在 127.0.0.1 而非 0.0.0.0
架构匹配的重要性:
- 在 ARM64 设备上必须使用 ARM64 架构的镜像
- 使用 platform: linux/arm64 强制指定架构
同网络容器通信:
- 同一自定义网络中的容器可以通过容器名互相访问
- 不需要将端口映射到宿主机
linuxserver vs 官方镜像:
- linuxserver 镜像使用 s6 进程管理器
- 官方镜像更轻量，直接运行 guacd 进程
- 在 ARM64 架构上官方镜像支持更好

常用排查命令汇总

# 检查容器状态
podman ps -a
podman inspect <container> | grep -A 5 "State"

# 检查镜像架构
podman inspect <image> | grep Architecture
podman manifest inspect <image> | grep architecture

# 进入容器检查
podman exec -it <container> /bin/sh

# 容器内检查命令
netstat -tuln
ps aux
which <command>
apk search <package>

# 查看容器日志
podman logs <container>

# 检查网络
podman network inspect <network>
podman port <container>

结论

问题根本原因是使用了 amd64 架构且不完整的 linuxserver/guacd 镜像。解决方案是改用官方 guacamole/guacd 镜像并明确指定 ARM64 平台。最终 guacd 服务正常监听 4822 端口，同网络的 Next Terminal 可通过 guacd:4822 正常连接。

guacd容器问题排查