在 Docker 微服务架构中，Spring Boot 应用无法通过 localhost:8085 访问同 compose 网络内的 Keycloak 容器，根本原因是 localhost 指向当前容器自身而非宿主机或目标服务；需改用 Docker 内部服务名（如 keycloak-service:8080）实现跨容器通信。
在 docker 微服务架构中，spring boot 应用无法通过 `localhost:8085` 访问同 compose 网络内的 keycloak 容器，根本原因是 `localhost` 指向当前容器自身而非宿主机或目标服务；需改用 docker 内部服务名（如 `keycloak-service:8080`）实现跨容器通信。
当 Keycloak 以容器方式部署（如 keycloak-service），而 Spring Boot 应用（如 auth-server）也运行于独立容器中时，容器内 localhost 并不等价于宿主机的 localhost。Docker 为每个服务自动创建一个共享的用户定义桥接网络（默认 docker-compose 网络），服务之间应通过 服务名（service name） 互相访问，而非 localhost 或宿主机 IP。
在您的 docker-compose.yml 中：
services:
keycloak-service:
image: 'keycloak/keycloak:latest'
container_name: keycloak-service
ports:
- "8085:8080" # 宿主机8085 → 容器内部8080Keycloak 实际监听的是容器内 8080 端口，且对外暴露的服务名为 keycloak-service。因此，auth-server 容器必须使用 http://keycloak-service:8080 才能通过 Docker 内网成功连接。
✅ 正确配置示例（修改 KeycloakConfig.java）：
@Configuration
public class KeycloakConfig {
@Value("${keycloak.server-url:http://keycloak-service:8080}")
private String serverUrl; // 推荐外部化配置，便于多环境切换
@Bean
public Keycloak keycloak() {
ResteasyClientBuilder resteasyClientBuilder = new ResteasyClientBuilderImpl();
Keycloak keycloak = KeycloakBuilder.builder()
.serverUrl(serverUrl) // ← 关键：使用服务名 + 容器内端口
.grantType(OAuth2Constants.PASSWORD)
.realm("master")
.clientId("admin-cli")
.username("admin")
.password("keycloak")
.resteasyClient(resteasyClientBuilder.connectionPoolSize(10).build())
.build();
// 创建 Realm 和 Client（注意：生产环境建议移出启动逻辑，避免重复创建）
try {
RealmRepresentation realm = new RealmRepresentation();
realm.setId("new-realm");
realm.setRealm("new-realm");
realm.setEnabled(true);
keycloak.realms().create(realm);
ClientRepresentation client = new ClientRepresentation();
client.setClientId("my-backend");
client.setRedirectUris(List.of("http://localhost:8081/*"));
client.setWebOrigins(List.of("http://localhost:8081"));
keycloak.realm("new-realm").clients().create(client);
} catch (Exception e) {
// 避免因 Realm 已存在导致启动失败（Keycloak 返回 409）
if (!e.getMessage().contains("409")) {
throw new RuntimeException("Failed to initialize Keycloak realm/client", e);
}
}
return keycloak;
}
}⚠️ 重要注意事项：
-
端口映射 ≠ 容器间通信端口：
ports: "8085:8080"仅开放给宿主机访问，容器间通信必须使用8080（即容器内部实际监听端口）； -
依赖顺序不能替代网络可达性：
depends_on仅控制启动顺序，不保证 Keycloak 已就绪；建议添加健康检查或重试机制（如spring-retry）； - 避免启动期强依赖：初始化 Realm/Client 属于管理操作，若 Keycloak 启动慢或临时不可用，会导致应用启动失败。推荐改为懒加载、定时任务或独立初始化脚本；
-
版本兼容性提醒：您当前混合使用 Spring Boot 2.6/2.7 和 Spring Security 3.x（
spring-boot-starter-security:3.0.4），存在重大版本不兼容风险（Spring Security 3+ 要求 Spring Boot 3.x）。请统一升级至 Spring Boot 3.2+ 及对应 Keycloak Admin Client（如22.0.5），否则可能引发ResteasyClient初始化异常或类冲突； -
安全加固建议：生产环境禁用
start-dev模式，改用start命令并配置 HTTPS、数据库持久化及管理员凭据加密。
总结：Docker 容器网络的本质是隔离与命名——localhost 是容器视角的“自己”，而服务名（如 keycloak-service）才是 Docker DNS 解析后的真实通信地址。始终以 http://<service-name>:<internal-port></internal-port></service-name> 替代 localhost，是微服务容器化部署的基石实践。
