网络安全事故很少来自“忘了用 HTTPS”这么简单。测试环境为了抓包临时信任用户安装的 CA、业务域名范围写得过宽、证书异常被统一忽略、WebView 与原生网络栈策略不一致，都会把临时调试口变成生产风险。HarmonyOS 的网络连接安全配置用于声明连接信任边界；在 HarmonyOS 7/API 26 适配中，更应该把它当作版本化安全契约，而不是发版前的配置补丁。

本文给出一套从威胁建模、环境分离、证书信任、明文阻断、错误处理到自动化验收的实践。配置字段请以目标 SDK 官方文档为准，示例重点是策略结构和工程门禁。

一、先建立连接资产清单

没有域名台账，就无法知道应该信任谁。按业务域、用途、数据级别和所有者登记所有外连目标。

interface EndpointAsset {
  host: string
  purpose: string
  dataLevel: 'PUBLIC' | 'ACCOUNT' | 'SENSITIVE'
  owner: string
  environments: Array<'DEV' | 'TEST' | 'PROD'>
  thirdParty: boolean
}

把 API、图片 CDN、上传、推送、地图、支付、埋点和 Web 页面都纳入。动态拼接的任意域名应视为高风险，而不是“方便扩展”。

二、默认拒绝，按需放行

网络策略应从“默认只允许安全连接”开始，对少数必要目标做精确规则。不要写一个覆盖所有子域甚至所有主机的例外。

interface ConnectionRule {
  domain: string
  includeSubdomains: boolean
  cleartextAllowed: boolean
  trust: Array<'SYSTEM_CA' | 'APP_CA' | 'USER_CA'>
}

const productionRule: ConnectionRule = {
  domain: 'api.example.com',
  includeSubdomains: false,
  cleartextAllowed: false,
  trust: ['SYSTEM_CA']
}

实际配置文件格式、资源路径和字段名称必须按官方“网络连接安全配置”文档生成，上面的 TypeScript 只是审查模型。

三、生产环境通常不应信任用户 CA

用户安装证书适合企业受管场景或开发抓包，却也可能允许中间人解密流量。生产消费者应用应明确评估是否需要信任用户 CA。

type BuildChannel = 'debug' | 'qa' | 'release'

function allowedTrust(channel: BuildChannel): string[] {
  if (channel === 'debug') return ['SYSTEM_CA', 'DEV_CA']
  if (channel === 'qa') return ['SYSTEM_CA', 'QA_CA']
  return ['SYSTEM_CA']
}

关键点是构建隔离：调试证书、测试域名和宽松规则不得仅靠运行时开关隐藏，而应不进入 release 包。

四、环境配置物理分离

开发、测试、预发布和生产的信任根与域名不同。建议用独立资源文件或构建变体生成最终配置，并对产物做静态检查。

{
  "channel": "release",
  "allowedHosts": [
    "api.example.com",
    "upload.example.com",
    "static.examplecdn.com"
  ],
  "allowCleartext": false,
  "allowUserCA": false
}

CI 不只检查源码，还要解包最终 HAP，确认真实生效的配置没有测试域名和测试证书。

五、明文 HTTP 例外必须可到期

旧设备或局域网硬件可能暂时只支持 HTTP。例外要限定域名、用途、负责人和删除日期。

interface SecurityException {
  ticket: string
  host: string
  reason: string
  owner: string
  expiresAt: string
  mitigation: string
}

function expired(e: SecurityException, today: string): boolean {
  return e.expiresAt < today
}

不能用“所有明文允许”解决一个局域网地址。对敏感数据，即使业务紧急也不应通过明文传输。

六、证书校验失败必须失败关闭

遇到证书过期、域名不匹配或链不可信时，客户端应中止连接，展示可恢复提示并上报非敏感错误分类。

type TlsFailure =
  | 'CERT_EXPIRED'
  | 'HOST_MISMATCH'
  | 'UNTRUSTED_CHAIN'
  | 'PROTOCOL_UNSUPPORTED'

function userMessage(error: TlsFailure): string {
  return '安全连接失败，请检查时间或网络后重试'
}

不要提供“继续访问”按钮，也不要在捕获异常后自动降级到 HTTP。

七、不要自定义一个不完整的证书校验器

为了实现证书锁定或私有 CA，有团队会自己解析证书，却漏掉有效期、域名、用途、撤销与链构建。优先使用系统信任和官方配置能力。

interface PinSet {
  host: string
  currentPins: string[]
  backupPins: string[]
  expiresAt: string
}

如确需锁定，必须准备至少一个备份 Pin、证书轮换流程、远端应急策略和过期提醒。锁定不是“越严越好”，配置失误会让全部用户断网。

八、Web 与原生网络栈统一策略

应用可能同时使用 HTTP 客户端、Web 组件、图片加载器、音视频 SDK 和第三方支付 SDK。任何一个组件绕过策略都会形成短板。

interface StackAuditItem {
  stack: 'HTTP_CLIENT' | 'ARKWEB' | 'IMAGE' | 'MEDIA' | 'THIRD_PARTY'
  usesHttps: boolean
  followsTrustPolicy: boolean
  handlesTlsErrorSafely: boolean
}

Web 页面重定向、iframe、图片和下载域也要纳入域名台账；不要只验证首页 URL。

九、日志保持可诊断但不泄密

安全连接失败需要定位，但日志不能记录完整令牌、Cookie、请求体和证书私钥。

interface SafeNetworkLog {
  hostHash: string
  errorClass: string
  networkType: string
  appVersion: string
  policyVersion: string
  timestamp: number
}

域名是否可直接记录取决于业务敏感性；查询参数通常应删除。客户端日志与服务端握手日志通过时间窗和请求 ID 关联。

十、自动化负向测试比“请求成功”更重要

测试环境准备有效证书、过期证书、错误域名、自签名证书、用户 CA、中间证书缺失和 HTTP 重定向等场景。

interface SecurityCase {
  name: string
  endpoint: string
  expected: 'ALLOW' | 'BLOCK'
  expectedError?: TlsFailure
}

const cases: SecurityCase[] = [
  { name: 'valid-chain', endpoint: 'https://valid.test', expected: 'ALLOW' },
  { name: 'expired', endpoint: 'https://expired.test', expected: 'BLOCK', expectedError: 'CERT_EXPIRED' },
  { name: 'http-redirect', endpoint: 'https://redirect-http.test', expected: 'BLOCK' }
]

每次更新证书、网络库、SDK 或安全配置后自动回归。

十一、证书轮换要双轨演练

服务端换证前，客户端要确认新证书链在系统信任范围内；如使用锁定，先发布同时接受新旧 Pin 的版本，再换服务端，最后移除旧 Pin。

type RotationStage = 'ADD_NEW' | 'SWITCH_SERVER' | 'REMOVE_OLD'

interface RotationPlan {
  stage: RotationStage
  minimumClientVersion: string
  rollbackDeadline: string
}

把证书到期监控纳入运维，不要等线上握手失败才发现。

十二、CI 安全门禁

network-security-gate:
  checks:
    - release_has_no_test_ca
    - release_has_no_debug_host
    - cleartext_is_disabled
    - exceptions_are_not_expired
    - negative_tls_cases_pass

门禁输出应能定位规则来源和所有者。对配置文件的任何修改要求安全评审，而不是普通文本变更直接合并。

十三、上线检查清单

• 已维护全部网络栈和外连域名台账；
• 默认拒绝明文连接，例外精确且可到期；
• release 构建不包含调试 CA、测试域名和宽松规则；
• 生产是否信任用户 CA 已有明确结论；
• 证书异常失败关闭，不回退 HTTP；
• 原生、ArkWeb、图片、媒体和第三方 SDK 策略一致；
• 日志不记录令牌、Cookie、请求体和敏感参数；
• 有证书轮换与回滚演练；
• 负向 TLS 用例进入 CI；
• 最终 HAP 产物经过静态审计。

结语

网络连接安全配置的价值，是把“客户端到底信任谁”从散落在代码和调试习惯里的隐式行为，变成可审查、可测试、可轮换的显式契约。HarmonyOS 7 适配时同时治理域名、信任根、构建变体、错误处理和证书轮换，才能避免为一次抓包或临时兼容留下长期后门。

官方参考

• 网络连接安全配置：https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/network-connection-security-configuration
• HarmonyOS 版本说明：https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/changelogs-600
• ArkWeb 页面加载问题定位：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/web-page-loading