故障诊断

1. 容器启动后无法通过`external_url`正常访问

此问题需要排查以下：

服务就绪状态

docker exec -it csghub-omnibus csghub-ctl status

端口映射配置

正常情况下，80 端口的对外映射端口应该改external_url中使用的端口保持一致。

示例：

......
    # Use block scalar style for better readability of complex configs
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        csghub:
          external_url: "http://csghub.example.com"
    
    # Ports mapping for accessing
    ports:
      - '80:80'

或者

    # Use block scalar style for better readability of complex configs
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        csghub:
          external_url: "http://csghub.example.com:8080"
    
    # Ports mapping for accessing
    ports:
      - '8080:80'

external_url解析的地址不能和 Docker 容器网络冲突（即不能使用 localhost, 127.0.0.1, 172.17.0.0/8, 172.21.0.0/8 等地址段）。
此外不应改在docker-compose.yaml中指定 hostname 参数，如指定不应和 external_url 使用的域名一样。

2. 容器无法启动，启动渲染配置文件出错

此问题多是由于environment.CSGHUB_OMNIBUS_CONFIG中的格式问题，此变量需要传入 YAML 格式的参数，缩进需要严格遵循 YAML 行为规范，尤其不能使用 TAB 制表位进行缩进。

其他问题可以提交反馈。

3. 修改端口号映射

目前对外暴露的端口号一共有以下：

服务	默认端口	用途
Nginx	80	主访问入口
Git SSH	2222	代码仓库
Casdoor	8000	认证中心
CSGShip	8001	CSGShip 访问入口（EE）
CSGShip-API	8002	CSGShip-API 访问入口（EE）
MinIO API	9000	对象存储 API
MinIO Console	9001	对象存储控制台

💡 说明：启用 TLS 时还需映射 443；容器内 Registry 服务监听 5000，通常仅通过 Nginx 反向代理访问，无需直接对外暴露。

修改 Nginx 端口号

services:
......
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        csghub:
          external_url: "http://csghub.example.com:8080" 
    ports:
      - '8080:80'   # 仅修改对外端口号
   ......

修改 Git Over SSH 端口号

services:
......
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        gitlab_shell:
          ssh_port: 22222
    ports:
      - '22222:22222'   # 修改内外端口号
   ......

修改 Casdoor 端口号

services:
......
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        casdoor:
          listen: "127.0.0.1:8005"
    ports:
      - '8005:8005'   # 修改内外端口号
   ......

修改 CSGShip 端口号

services:
......
    environment:
      CSGHUB_OMNIBUS_CONFIG: | 
        csgship:
          listen: 
            frontend: "127.0.0.1:8006"
            api: "127.0.0.1:8007"
    ports:
      - '8006:8006'   # 修改内外端口号 
      - '8007:8007'   # 修改内外端口号
   ......

修改 Minio 端口号

services:

    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        csghub:
          external_url: "http://csghub.example.com:8080" 
        server:
          s3: 
            endpoint: "csghub.example.com:9005"
            internal_endpoint: "127.0.0.1:9000"
        portal:
          s3:
            endpoint: "csghub.example.com:9005"
        registry:
          storage:
            s3:
              region_endpoint: "http://csghub.example.com:9005"
    ports:
      - '9005:9000'   # 仅修改对外端口号
      - '9006:9001'   # 仅修改对外端口号
   ......

4. 反馈

对于遇到的其他问题，请反馈给我们。

1. 容器启动后无法通过external_url正常访问​

2. 容器无法启动，启动渲染配置文件出错​

3. 修改端口号映射​

4. 反馈​

1. 容器启动后无法通过`external_url`正常访问

2. 容器无法启动，启动渲染配置文件出错

3. 修改端口号映射

4. 反馈