企业官网建设流程全解析

开了多年的 Terraform，我一直觉得 Azure 容器注册表（ACR）的域名是个“看起来简单、用起来藏坑”的东西。创建完azurerm_container_registry之后，你手里会拿到一个类似myregistry.azurecr.io的login_server字符串，表面上直接复制粘贴就行。可真到了要把这个域名拼进镜像地址、传给 CI 管道、塞给 Kubernetes 配置，或者从里面反向提取注册表名称时，字符串操作的细节就全暴露出来了。这篇文章就把我在实际项目里处理 ACR 域名的那些手法、踩过的坑和最终沉淀下来的习惯，完整整理一遍。

1. 到底哪里需要“动”ACR 域名：从登录服务器到镜像地址的常见链路

先说结论：大部分场景里，我们不是要“创造”ACR 域名，而是要从 Terraform 已有的资源属性里把它取出来，再做拆分、拼接、条件处理，最后变成另一个系统能直接消费的字符串。

最常见的需求集中在这几条链路上。

第一，镜像拉取地址。你在 ACR 里推了一个镜像checkout:v1.2.3，完整地址是myregistry.azurecr.io/checkout:v1.2.3。kubectl、Container App、容器组、流水线脚本里要用的都是这个完整地址，而不是拆开的注册表域名和镜像名。过去我见过团队在 AKS 的 deployment YAML 里硬编码myregistry.azurecr.io/checkout:v1.2.3，结果换环境、换版本时漏改地址，排查起来特别头大。既然注册表是用 Terraform 建出来的，那这个地址就该从 Terraform 的输出或 local 变量里“长”出来，而不是人肉复制。

第二，注册表名称与域名的互相转换。ACR 资源有两个属性，name是纯注册表名，比如myregistry；login_server是完整的myregistry.azurecr.io。有些接口只接受注册表名称，比如创建角色分配时scope要填注册表资源 ID，比如 RBAC 命名。有些接口只接受完整域名，比如登录、拉取、推送。所以你要在两种形态之间灵活切换：从login_server去掉后缀得到name，或者用name拼出login_server。

第三，环境差异化。测试环境叫myregistry-dev，生产环境叫myregistry-prod，或者同一个注册表在多个地域有复制副本，登录服务器地址会带上地域后缀。这些差异如果靠人肉拼接，很容易搞错。更好的做法是让 Terraform 根据变量、地域、环境去计算域名，然后统一输出。

第四，Kubernetes 的 imagePullSecret 配置。当 AKS 需要从 ACR 拉取私有镜像，而你没有启用 Managed Identity 集成时，就得生成一个包含认证信息的 Docker config JSON，再转成 Kubernetes Secret。这个 JSON 的auths字段，key 恰好就是 ACR 的login_server字符串，value 里还嵌着用username:password拼接后做 Base64 的结果。这几乎就是为字符串操作“量身定做”的真实场景。

所以你发现没有，这四类需求本质上都在做同一件事：把 ACR 的域名当作字符串数据，在 Terraform 的 locals、variables、outputs 之间流动、变形。接下来我们就一步步拆开看。

2. 从 azurerm_container_registry 拿到域名：别把属性值当成单纯字符串

在 Terraform 里，拿到 ACR 域名最直接的方式就是引用资源属性。

resource "azurerm_resource_group" "rg" { name = "rg-app-demo" location = "eastasia" } resource "azurerm_container_registry" "acr" { name = "shopregistry" resource_group_name = azurerm_resource_group.rg.name location = azurerm_resource_group.rg.location sku = "Premium" admin_enabled = true }

创建完成后，azurerm_container_registry.acr.login_server的值就是shopregistry.azurecr.io。注意，这个值不带https://前缀，也不带结尾的/。这是 Azure API 返回的原始 FQDN。很多初学者会在使用时自己加https://，但后面拼镜像地址时反而画蛇添足。

azurerm_container_registry.acr.name则是shopregistry，不包含.azurecr.io后缀。这两个属性看起来只差了一小段，可一旦把它们用到不同接口里，差异就会被放大。比如创建 AKS 整合的azurerm_role_assignment时，scope 指向注册表 ID，而 principal 不必关心域名；但在给容器运行时配置加镜像前缀时，基本都用login_server。

有些场景下，注册表不在当前 Terraform 配置中创建，而是已经存在于订阅里。这时要用 data source 读取：

data "azurerm_container_registry" "acr" { name = "shopregistry" resource_group_name = "rg-app-demo" } output "login_server" { value = data.azurerm_container_registry.acr.login_server }

data source 的属性和 resource 基本一致，拿到login_server后同样可以做后续字符串操作。我通常建议：如果注册表由同一套 Terraform 管理，优先直接引用 resource；如果由别人创建或跨状态文件共享，用 data source。两种方式拿到的字符串内容是相等的，后续处理逻辑完全可以复用。

还有一个容易忽略的点：admin_enabled = true时，Terraform 才会给你admin_username和admin_password两个属性；admin_enabled = false时，这两个值会是null。如果你在 locals 里直接拼它们，比如format("%s:%s", var.username, var.password)，一旦密码是null，format 会报错。处理时一定要先判断再拼接，或者干脆避免依赖 admin 账号，改用 Managed Identity。后面我会专门讲这个坑。

3. 字符串函数怎么选：replace、split、trim 还是 regex

这是整篇最核心的部分。Terraform 内置的字符串函数不少，但处理 ACR 域名时真正高频的其实就那么几个。我把它们的适用场景和坑整理成了一张表，方便对照。

先看最常见的需求：从shopregistry.azurecr.io提取出shopregistry。

我推荐的第一选择是trimsuffix：

locals { registry_name = trimsuffix(azurerm_container_registry.acr.login_server, ".azurecr.io") }

理由很简单：这是语义最清晰的一种。读代码的人一眼就能看出“我要把后面的.azurecr.io尾巴切掉”。它不会像split那样产生歧义，也不会像regex那样引入难以维护的匹配串。

如果注册表可能在中国区使用，后缀就变成.azurecr.cn。这时候可以用变量把后缀抽象出来：

variable "azure_cloud_suffix" { type = string default = "azurecr.io" } locals { registry_name = trimsuffix(azurerm_container_registry.acr.login_server, ".${var.azure_cloud_suffix}") }

注意我前面写了.加后缀，因为login_server完整值里本来就有那个点。

replace也能做同样的事，但语义上更“粗”：

locals { registry_name = replace(azurerm_container_registry.acr.login_server, ".azurecr.io", "") }

如果你确实知道字符串里只有那一段需要替换，这样写没问题；但replace是全文替换，万一域名叫azurecr.ioops.azurecr.io这种奇怪组合（Azure 其实不会允许，但作为通用逻辑），可能会误伤。所以我个人只用replace处理“字面量替换”的场景，比如把:latest换成:main。

再来看split。

locals { registry_name = split(".", azurerm_container_registry.acr.login_server)[0] }

这种写法很简洁，但对输入格式的假设非常强：它假设域名第一段就是注册表名，并且后面一定有., 所以索引[0]永远存在。对于 ACR 标准域名，这个假设能成立，可一旦遇到带有地域副本的登录服务器，比如shopregistry.eastasia.azurecr.io，split(".", ...)[0]得到的是shopregistry，你依然会拿到注册表名，但是你可能想要的却是“带地域标识的完整前缀”。这个细节特别容易翻车。

regex是最强大也最容易过度使用的方案。比如要抽取shopregistry.eastasia.azurecr.io中的“注册表名 + 地域前缀”，可以这样：

locals { full_prefix = replace(azurerm_container_registry.acr.login_server, "/\\.azurecr\\.(io|cn)$/", "") }

这里要用replace配合正则模式（模式包在/ /中）。replace函数在第二个参数以/开头时，Terraform 会把它当正则处理；否则按字面匹配。这个行为很隐蔽，我见过不少同事在非正则需要处误写了/xxx/格式。正则的优点是能同时适配不同云环境和地域后缀，但缺点是阅读门槛高、出错了不好查。我的原则是：能用trimsuffix就不用regex，只有后缀不固定、又有明确的格式规则时才上正则。

最后，format和join通常用来做“合成”而不是“拆分”。我一般这样选：如果拼接的段数少、并且中间固定要用斜杠或冒号，直接用format；如果段数多、还是动态数组，用join。举两个对比：

locals { image_full = format("%s/%s:%s", local.login_server, local.app_name, local.image_tag) } locals { image_full = join("/", [local.login_server, local.app_name, local.image_tag]) }

第一行的意图非常直白：三段结构login_server / app_name : tag。第二行适合段数可能变化的场景，但注意join不会自动加冒号，tag 拼接还得自己处理。所以一般我固定用format。

4. 案例实操：用 locals 把域名拼成完整的镜像引用与 Docker 配置

讲完函数选择，我们把它们组合到一个完整案例里。假设团队正在用 Terraform 部署一套微服务基础设施，ACR 已经创建好，现在要为每个服务生成完整的镜像地址，并且给不启用 Admin 账号的场景留好变量位。

先定义输入：

variable "environment" { type = string default = "dev" } variable "image_tag" { type = string default = "" } variable "auto_append_tag" { type = bool default = true }

然后建立 locals 计算层。这个层的作用很纯粹：把核算逻辑集中起来，不在资源块里写一大串复杂表达式。

locals { app_list = [ "checkout", "payment", "inventory", ] env_suffix = var.environment == "prod" ? "" : "-${var.environment}" acr_name = "shop${local.env_suffix}" login_server = format("%s.azurecr.io", local.acr_name) image_tag = var.image_tag != "" ? var.image_tag : "latest" image_map = { for app_name in local.app_list : app_name => format("%s/%s:%s", local.login_server, app_name, local.image_tag) } } output "image_map" { value = local.image_map }

这里有几个值得留意的设计。

第一，acr_name用了环境后缀拼接。别小看这个join与compact的组合优势。如果我用简单写法：

acr_name = "shop-${var.environment}"

那么在prod环境会得到shop-prod，而很多团队希望生产环境的注册表不带后缀。上面的写法用var.environment == "prod" ? "" : "-${var.environment}"解决了这一点。更通用、可以复用的写法是用compact和join过滤掉空段：

locals { acr_name = join("-", compact(["shop", var.environment == "prod" ? "" : var.environment])) }

compact会去掉空字符串，于是prod时数组变成["shop"]，下划线结果只是shop；dev时数组是["shop", "dev"]。如果你担心join在空段之间留下双连字符，compact就是你的救星。

第二，image_map是 for 表达式，它遍历了每个应用名，把login_server作为前缀，生成完整的镜像引用。这种写法比手写三个 resource 或 output 好维护得多。以后新增服务，只要往app_list里加一行，镜像我这里就自动生成。

第三，image_tag的逻辑。很多时候 CI 流水线没传 tag，我们希望默认用latest；但var.image_tag可能是""而不是null。var.image_tag != ""这个判断就比coalesce稳妥。coalesce对空字符串本身还不错，但空字符串不等于 null，如果代码里混用，很容易踩坑。

再扩展一个真实场景：生成 Docker config JSON，用于 Kubernetes imagePullSecret。

这个场景对字符串拼接的要求，比单纯拼镜像地址更复杂。你需要构造这个结构：

{ "auths": { "shop.azurecr.io": { "username": "adminuser", "password": "pwd", "auth": "YWRtaW51c2VyOnB3ZA==" } } }

用 Terraform 的jsonencode和base64encode来实现：

resource "azurerm_container_registry" "acr" { name = local.acr_name resource_group_name = azurerm_resource_group.rg.name location = azurerm_resource_group.rg.location sku = "Premium" admin_enabled = true } locals { docker_config_json = jsonencode({ auths = { (azurerm_container_registry.acr.login_server) = { username = azurerm_container_registry.acr.admin_username password = azurerm_container_registry.acr.admin_password auth = base64encode(format("%s:%s", azurerm_container_registry.acr.admin_username, azurerm_container_registry.acr.admin_password )) } } }) }

注意(azurerm_container_registry.acr.login_server)外面那对括号，这是 Terraform 里在jsonencode的 map key 中嵌入表达式的标准写法，没有括号会被当成立即字符串 key。我第一次写时漏掉括号，结果得到的 JSON 直接用了字面量"azurerm_container_registry.acr.login_server"作为 key，诡异得很。后来 set 了terraform console一眼才发现问题。

format("%s:%s", username, password)在这儿很不起眼，但它就是auth字段 Base64 的输入源。你可以把它提到一个独立的 local 中，方便做日志脱敏或复用：

locals { acr_admin_auth = format("%s:%s", azurerm_container_registry.acr.admin_username, azurerm_container_registry.acr.admin_password ) acr_auth_b64 = base64encode(local.acr_admin_auth) }

不过我必须提醒：admin_password在 Terraform 中默认会被标记为敏感值。如果你把它写进imagePullSecret，经过jsonencode之后，整个 JSON 也会带上敏感属性。这部分要配合sensitive = true的 output 使用，别在 CI 日志里明文打印。

5. 边界情况复盘：后缀变化、地域副本、空值和引号陷阱

这一节说的都是我在生产环境里真正遇到过的状况，每一条都值得记进自己的 check-list。

后缀不只有.azurecr.io。如果注册表部署在 Azure 中国区，标准域名是.azurecr.cn。虽然大部分读者用的是国际版，但只要你的代码要考虑多云、多环境，就一定不要把后缀硬编码在format里。正确做法是把后缀抽成变量或 local：

locals { cloud_domain = try(var.cloud_env_suffix, "azurecr.io") login_server = format("%s.%s", local.acr_name, local.cloud_domain) }

这里用try防一手：如果var.cloud_env_suffix类型没定义，或者外部没传，就用默认值。注意try更适合处理“表达式可能报错”的兜底，而普通变量默认值用default更明确。

地域副本会让域名多一段。ACR 开启异地复制后，你可以在另一个地域获得一个复制端点，登录服务器形如shopregistry.eastasia.azurecr.io。很多人在处理这种域名时，第一个反应就是split(".", ...)，但一旦你确实需要“去掉.azurecr.io后缀”而不是“取第一段”，split就会拿错。比如你想得到shopregistry.eastasia这个完整前缀，用trimsuffix就能正确去掉尾巴；用split只能拿到shopregistry。字符串操作的粒度，取决于你业务里到底要哪一段，千万别图省事一刀切。

空字符串和 null 的区别。Terraform 的null与空字符串""语义完全不同。replace、format遇到null会直接报错，而空字符串通常不会。所以当你从变量或 data source 拿值来拼字符串时，养成先做空值归一化的习惯：

locals { tag = coalesce(var.image_tag, "latest") tag = var.image_tag == null ? "latest" : var.image_tag }

上面两行都行，但注意第一行里coalesce只处理null，如果var.image_tag被显式设成""，它依然返回空字符串。所以如果你更关心“是否为空”，就要用第二种显式判断。

引号的转义问题。在 locals 里写复杂字符串，尤其是用jsonencode或templatefile时，反斜杠和双引号经常需要转义。比如你想在 JSON 里生成一个包含\"的值，直接写在 locals 里会非常难读。我的经验是：能交给jsonencode生成的 JSON 结构，尽量别用手写字符串；手写字符串时，把特殊字符抽到独立变量里，并加上注释解释用途。写完后用terraform console验证一次输出，别等 apply 后才发现多了一堆转义符。

sensitive 值别直接参与字符串运算后打印。在 Terraform 里，sensitive标记能跟随整个表达式传播。admin_password是敏感值，format("%s:%s", admin_username, admin_password)也会变成敏感结果。如果你把它存进 output，输出会显示“敏感”而不是明文。这本来是好事，但有些人为了调试而给 output 加sensitive = false，等于把密码明文暴露在 stdout 或 CI 日志里，极其危险。处理 ACR 凭证相关字符串时，安全第一，调试信息另外设计脱敏输出。

硬编码域名带来的隐患。我在很多遗留代码里见过login_server = "myreg.azurecr.io"，原因要么是注册表早已存在、懒得用 data source，要么是图省事。结果一旦订阅迁移或注册表重建，硬编码的域名就成了定时炸弹。更合理的做法是至少用data "azurerm_container_registry"去读。Terraform 的价值之一就是让资源和关联信息保持更新，字符串操作同样要建立在这个基础上。

6. 几个我觉得值得长期保留的字符串处理习惯

最后分享一些我踩过不少次坑之后沉淀下来的习惯，它们能让你的 Terraform 代码在维护半年后依然好读、好改。

先用terraform console快速验证字符串函数。当我不确定trimsuffix还是regex能满足需求时，不会直接改代码，而是先跑terraform console，把真实的login_server值粘进去试。Terraform 不会执行 apply，安全又高效。比如：

> trimsuffix("shopregistry.azurecr.io", ".azurecr.io") "shopregistry"

看见输出符合预期，再把它写进 locals，避免一次一次地 plan、apply 试错。

把字符串处理集中到一个 locals 块或独立locals.tf。不要在每个 resource 或每个 output 里散落replace、split。我习惯在文件顶部建一个locals，专门放 ACR 域名相关的派生值：acr_name、login_server、image_prefix、docker_config_json。这样同事 review 时，只扫一眼 locals 层，就能知道整个基础设施依赖哪些域名和地址。集中管理还有一个好处：如果某天域名规则改变，只需要改一处。

变量类型要前置收紧。与其在 locals 里反复判断var.environment == "prod"、var.image_tag != ""，不如在variable的定义里加validation。比如 environment 只允许dev、staging、prod几个值，image_tag 可以限制必须以字符串开头或都用latest。Terraform 的 validation 规则虽然不直接做字符串操作，但它能提前挡住绝大多数错误输入，把问题挡在字符串函数执行之前。

用 output 把字符串结果“发布”出去。我从不把login_server只留在 locals 里藏着。无论最终消费方是脚本、CI 还是另一个 Terraform 工作区，都要通过 output 暴露至少这几个值：

output "acr_login_server" { value = azurerm_container_registry.acr.login_server } output "acr_admin_username_b64" { value = local.acr_auth_b64 sensitive = true }

CI 里可以用terraform output -raw acr_login_server拿到纯字符串，避免了再写一层 grep 或 sed 去解析状态文件。如果只有 local，跨工作区引用就会变得别扭。

灵活配合templatefile做批量渲染。字符串函数的能力边界是“单行处理”，如果要把域名嵌入一整段 YAML、脚本或 Docker 配置模板，templatefile往往比format更适合。你可以在模板里写%{ for ... }循环，把 ACR 域名作为模板变量传进去。像我之前生成 Kubernetes Secret 的 YAML 场景，templatefile和jsonencode结合使用，生成的配置可读性和稳定性都比手写字符串强很多。它的核心仍然是字符串处理，只是换了一个更结构化的载体。

再回到开头那句话：ACR 域名本身并不复杂，复杂的是它要出现在不同的上下文里。学会用 Terraform 的字符串函数把它拆开、拼好、抽象成变量，再通过 locals 和 output 集中管理，你会发现自己少了很多“明明域名没错，但就是连不上”的深夜排查时间。希望这篇整理能帮你把 ACR 域名这个小小的字符串，处理得干干净净、明明白白。