HarmonyOS HTTPS 证书边界实战：域名、环境、CA 与发布校验

Vanbin.Mr

649人浏览 · 2026-08-20 09:57:10

Vanbin.Mr · 2026-08-20 09:57:10 发布

HarmonyOS HTTPS 证书边界实战：域名、环境、CA 与发布校验

网络安全配置经常在临近发布时暴露问题：测试环境域名混进生产包，自签证书只在开发机可用，HTTPS 证书过期导致接口全挂，预发布和生产配置被同一个开关控制。HTTPS 证书边界治理要把环境、域名、CA 信任、证书有效期和发布检查都纳入工程流程。

请添加图片描述

本文解决：环境怎么隔离，域名白名单怎么写，证书策略如何表达，发布前怎么避免测试配置进入生产。

1. 证书问题先从环境边界查

很多证书事故不是 TLS 本身的问题，而是环境串了。生产包请求测试域名，测试证书不被信任，用户看到的就是接口失败。

请添加图片描述

环境	域名	证书要求
开发	dev.example.com	可用内部证书
预发	staging.example.com	接近生产
生产	api.example.com	可信 CA、有效期明确

2. HTTPS 资料边界和工程目录

HarmonyOS 网络安全需要关注 HTTPS、证书链、CA 证书和网络安全配置。工程上要把环境配置和发布校验分开。

资料入口	工程落点
HTTP 数据请求	请求时使用 HTTPS 地址
HTTPS 证书校验	证书校验和安全连接
网络安全配置	域名和 CA 信任边界

entry/src/main/ets/common/security/
  EnvConfig.ets
  DomainAllowList.ets
  CertificatePolicy.ets
  ReleaseGuard.ets
  SecurityAudit.ets

3. `EnvConfig` 区分环境

export type AppEnv = 'dev' | 'staging' | 'production'

export interface EndpointConfig {
  env: AppEnv
  apiBase: string
  cdnBase: string
}

export const EndpointTable: Record<AppEnv, EndpointConfig> = {
  dev: { env: 'dev', apiBase: 'https://dev.example.com', cdnBase: 'https://dev-cdn.example.com' },
  staging: { env: 'staging', apiBase: 'https://staging.example.com', cdnBase: 'https://staging-cdn.example.com' },
  production: { env: 'production', apiBase: 'https://api.example.com', cdnBase: 'https://cdn.example.com' }
}

环境配置要集中，不能在页面或仓库层散落域名字符串。

4. `DomainAllowList` 限制请求目标

export class DomainAllowList {
  allowedHosts(env: AppEnv): string[] {
    const cfg = EndpointTable[env]
    return [new URL(cfg.apiBase).hostname, new URL(cfg.cdnBase).hostname]
  }

  verify(env: AppEnv, url: string): boolean {
    const host = new URL(url).hostname
    return this.allowedHosts(env).includes(host)
  }
}

白名单可以防止临时调试域名进入生产包。

5. `CertificatePolicy` 表达证书要求

export interface CertificateRequirement {
  host: string
  issuer: string
  expireBeforeDays: number
  pinningRequired: boolean
}

export class CertificatePolicy {
  requirement(env: AppEnv): CertificateRequirement[] {
    if (env === 'production') {
      return [
        { host: 'api.example.com', issuer: 'Trusted CA', expireBeforeDays: 30, pinningRequired: true },
        { host: 'cdn.example.com', issuer: 'Trusted CA', expireBeforeDays: 30, pinningRequired: false }
      ]
    }
    return [{ host: `${env}.example.com`, issuer: 'Internal CA', expireBeforeDays: 7, pinningRequired: false }]
  }
}

生产证书策略要比测试环境严格，尤其是有效期和固定证书策略。

6. `ReleaseGuard` 发布前检查

请添加图片描述

export interface ReleaseCheckResult {
  passed: boolean
  errors: string[]
}

export class ReleaseGuard {
  check(env: AppEnv, urls: string[]): ReleaseCheckResult {
    const allow = new DomainAllowList()
    const errors: string[] = []
    if (env !== 'production') errors.push('发布包环境不是 production')
    for (const url of urls) {
      if (!url.startsWith('https://')) errors.push(`${url} 不是 HTTPS`)
      if (!allow.verify(env, url)) errors.push(`${url} 不在生产白名单内`)
    }
    return { passed: errors.length === 0, errors }
  }
}

发布检查要在打包前执行，不要等审核或线上用户发现。

7. `SecurityAudit` 记录安全配置

export interface SecurityAuditRecord {
  env: AppEnv
  host: string
  item: 'domain' | 'certificate' | 'ca' | 'release'
  result: 'pass' | 'fail'
  reason?: string
}

export class SecurityAudit {
  private readonly records: SecurityAuditRecord[] = []

  append(record: SecurityAuditRecord): void {
    this.records.push(record)
  }

  failures(): SecurityAuditRecord[] {
    return this.records.filter(item => item.result === 'fail')
  }
}

安全配置的变更要留下记录，方便发布审查和事故复盘。

8. 页面和网络层如何使用

export function buildApiUrl(env: AppEnv, path: string): string {
  const base = EndpointTable[env].apiBase
  if (!path.startsWith('/')) throw new Error('接口路径必须以 / 开头')
  return `${base}${path}`
}

业务层只传路径，不能自己拼域名。域名由环境配置统一控制。

9. HTTPS 发布验收动作

场景	操作	预期结果
生产包	检查环境	必须是 production
域名检查	扫描接口地址	全部命中白名单
非 HTTPS	写入 http 地址	发布检查失败
证书过期	模拟剩余天数不足	发布前拦截
测试域名	混入 staging	直接失败

export function assertProductionEndpoint(url: string): void {
  if (!url.startsWith('https://')) throw new Error('生产接口必须使用 HTTPS')
  if (!new DomainAllowList().verify('production', url)) throw new Error('生产接口不在白名单内')
}

10. 证书边界异常排查表

证书问题要从环境、域名、证书链和有效期四层定位。

现象	优先查看	处理建议
生产接口全失败	证书有效期	提前告警
只有测试机正常	CA 信任	不把内部 CA 带到生产
请求到测试环境	EnvConfig	发布包冻结生产配置
某个域名失败	白名单和证书链	单域名排查
审核问网络安全	安全配置记录	提供域名、CA、HTTPS 说明

发布前建议生成一份安全配置摘要，交给测试和审核资料一起归档。摘要不需要暴露密钥，只列出环境、域名、HTTPS 状态、证书策略和最近一次检查结果。

export interface ReleaseSecuritySummary {
  env: AppEnv
  domains: string[]
  httpsOnly: boolean
  certificatePolicyCount: number
  generatedAt: number
}

export function buildReleaseSummary(env: AppEnv): ReleaseSecuritySummary {
  const domains = new DomainAllowList().allowedHosts(env)
  const policies = new CertificatePolicy().requirement(env)
  return {
    env,
    domains,
    httpsOnly: domains.every(host => host.length > 0),
    certificatePolicyCount: policies.length,
    generatedAt: Date.now()
  }
}

这份摘要的价值在于“发布前可复核”。如果生产包里出现测试域名，摘要会马上暴露；如果证书策略数量异常，也能在提交审核前拦下来。

HTTPS 证书复现场景：给读者一组可执行核验

证书边界要按环境验证。测试域名、正式域名、证书过期和 CA 变化都要有记录，避免发版后才发现握手失败。

核验维度	读者需要准备的证据
输入	页面入口、用户动作、关键参数
过程	日志、状态变化、异常分支
输出	UI 表现、回调结果、持久化结果
回归	同场景重复执行后的结果

interface HttpsReplayCase {
  host: any
  env: any
  certExpireDays: any
  caMatched: any
}

const replay87: HttpsReplayCase = {
  host: 'sample',
  env: 'sample',
  certExpireDays: 'sample',
  caMatched: 'sample',
}

function assertReplay87(item: HttpsReplayCase): void {
  if (item.env === 'prod' && !item.caMatched) throw new Error('正式环境 CA 不匹配')
}

这组核验把证书环境和 CA 匹配情况写清楚，适合在测试域名切正式域名前使用。

证书环境回放表：把文章方法变成可复现动作

HTTPS 证书问题常发生在测试环境切正式环境。建议准备测试域名、正式域名、过期证书和错误 CA 四种记录，验证发布前不会带错配置。

回放动作	核验方式
测试域名隔离	准备输入、执行操作、记录结果、给出结论
正式域名匹配	准备输入、执行操作、记录结果、给出结论
过期证书告警	准备输入、执行操作、记录结果、给出结论
错误 CA 阻断	准备输入、执行操作、记录结果、给出结论

HTTPS 证书边界要跟环境绑定。读者可以把测试域名、预发域名、正式域名分别列入表格，记录证书过期时间、CA 来源和域名匹配情况。发布前如果测试 CA 混入正式环境，或者正式域名证书即将过期，就应该阻断发布，而不是等用户请求失败后再定位。

证书发布的落地边界：不要把边界留给读者猜

HTTPS 证书治理要进入发布流程。证书过期时间、域名匹配、环境隔离、CA 来源都应该在发版前确认。读者如果只在请求失败后排查证书，线上问题已经发生。

落地项	处理要求
证书过期提前提醒	需要有明确输入、处理边界和失败兜底
域名和环境绑定	需要有明确输入、处理边界和失败兜底
测试 CA 不进正式包	需要有明确输入、处理边界和失败兜底
发布前保留核验记录	需要有明确输入、处理边界和失败兜底

这类边界写清楚后，读者不需要猜哪些逻辑属于页面、哪些属于服务、哪些属于发布前验收。文章的价值也会从“讲了一个功能”变成“给了一套可迁移的工程判断”。