semtech/mu-identifier

mu-identifier

mu-identifier 是一个 HTTP 代理，用于识别用户会话，以便微服务可以对其进行操作。它能识别特定的浏览器代理（特定设备上的特定浏览器），生成会话标识并通过 MU-SESSION-ID 头传递给后端服务，同时负责缓存当前用户的访问权限。

教程

将标识符添加到堆栈

mu-identifier 是请求到达的入口。在仅运行一个应用的服务器上，标识符通常发布在 80 端口（例如开发环境）。

将标识符添加到 docker-compose.yml 的 services 块中：

yaml
services:
  identifier:
    image: semtech/mu-identifier:1.9.1
    links:
      - dispatcher:dispatcher

作为基础组件，标识符会将所有请求转发给调度器（dispatcher）。以上配置片段足以将标识符添加到堆栈中。

操作指南

如何使堆栈可从外部主机访问（CORS）

跨域资源共享（CORS）是一种允许访问域 A 的浏览器使用域 B 上 API 的方法。

当外部站点用作 API 时，浏览器会发送 OPTIONS 请求，并检查 Access-Control-Allow-Origin 头是否包含有效的远程源。* 表示允许所有远程主机访问，本示例将使用该值。

注意：此方法存在一些注意事项。为了传递 cookie，可能需要发送额外的头（常见的有 access-control-allow-headers: content-type,accept 和 access-control-allow-methods: *）。如需支持此功能，请创建 PR 或在 issue 中讨论。

标识符可以为所有响应添加此头。通过设置 DEFAULT_ACCESS_CONTROL_ALLOW_ORIGIN_HEADER 值实现，可根据使用场景添加到 docker-compose.yml 或 docker-compose.override.yml 中。假设应用始终为公共访问，以下是添加到 docker-compose.yml 的配置：

yaml
services:
  identifier:
    ...
    environment:
      DEFAULT_ACCESS_CONTROL_ALLOW_ORIGIN_HEADER: "*"

使标识符应用此更改，需使用新环境变量重新创建服务：

bash
> cd /path/to/your/app
> docker-compose up -d

接下来，需确保对远程 OPTIONS 请求始终返回成功响应。最简单的方法是对调度器收到的任何 OPTIONS 请求返回 200 状态码。大多数服务不需要专门处理 OPTIONS 请求，可按以下方式配置：

elixir
# /config/dispatcher.ex
options "*_path" do
  send_resp(conn, 200, "Option calls are accepted by default")
end

为使调度器应用新路由，需重启调度器：

bash
> cd /path/to/your/app
> docker-compose restart dispatcher

完成后，API 即可从外部源访问。

登录后重新计算允许的组（访问权限）

如果服务更新了当前会话的访问权限但未自行计算，需通知标识符清除 mu-auth-allowed-groups 头，并在后续请求中不向后端提供该头，从而触发后端重新计算 mu-auth-allowed-groups。

登录系统建议设置正确的访问权限，但多数情况下并非必需（可简化登录服务）。此类服务需在响应中发送 mu-auth-allow-groups: CLEAR 头。

以下是 JavaScript 服务的示例：

javascript
// app.js
app.post('/login', function (req, res) {
  // 更新数据库状态
  res
    .header('mu-auth-allow-groups', 'CLEAR')
    .send(/* 响应体 */);
});

这将确保用户下次请求到达数据库时，计算新的 mu-auth-allowed-groups 值。

允许新请求的缓存命中

用户首次执行可能已缓存的请求时，通常不会命中缓存。本教程将修复示例堆栈中的此问题。

缓存基于会话附加的访问权限响应请求，但用户首次请求数据时，访问权限未知。访问权限在用户请求首次命中数据库时计算，因此需为尚无访问权限的用户提供默认访问权限。mu-identifier 支持定义此类权限。

首先，确定未登录用户的访问权限。实际中通常很简单，可通过 mu-authorization 中的定义找到：每个具有 %AlwaysAccessible{} 访问权限的 %GroupSpec{}，记录其权限名称。常见的权限数组为 [public, clean]。

需将这些组名转换为有效的 mu-auth-allowed-groups 头字符串（详见 mu-authorization 文档）。该头字符串是包含允许组的数组的 JSON 字符串，每个组是一个对象，包含 name（组名）和 variables（特殊化数组，此处为空数组）。

例如，[public, clean] 转换后的 JSON 字符串为：

json
"[{\"variables\":[],\"name\":\"public\"},{\"variables\":[],\"name\":\"clean\"}]"

可在 mu-identifier 的环境变量中设置此字符串，通常添加到 docker-compose.yml（应用级配置，多环境共享）：

yaml
# docker-compose.yml
services:
  identifier:
    environment:
      DEFAULT_MU_AUTH_ALLOWED_GROUPS_HEADER: "[{\"variables\":[],\"name\":\"public\"},{\"variables\":[],\"name\":\"clean\"}]"

应用此配置需重新创建标识符服务：

bash
> cd /path/to/your/app
> docker-compose up -d

讨论

mu-identifier 的核心功能是什么？

mu-identifier 是所有请求的首个入口服务，主要职责是识别发送请求的用户。它不直接连接数据库，仅基于接收的信息进行处理并传递。

由于其在堆栈中的唯一入口位置，它适合添加响应清理、请求通用增强、会话状态维护等逻辑。目前，其职责包括：

• 设置用户代理
• 清理响应头
• 简化缓存
• 缓存用户授权组

能否用 Nginx 等其他代理替换此服务？

理论上可以用其他技术替换，但为保持一致性并确保能自主控制逻辑调整，使用自定义代理更合理。例如，缓存 mu-auth-allowed-groups 时，微服务需传递该头但不应对外暴露，通过 mu-identifier 可透明实现此功能，不影响其他堆栈。

为何使用 Elixir 开发？

Elixir 运行在 BEAM 虚拟机上，擅长以低开销维护长连接，且具有容错性，减少因 bugs 导致的崩溃。Elixir 比 Erlang 更易读，因此选择 Elixir。

参考

所有配置通过环境变量完成。

外部主机

http://dispatcher/：mu-identifier 默认将所有请求转发到 http://dispatcher/。如需访问其他后端，添加链接即可。

环境变量

• DEFAULT_ACCESS_CONTROL_ALLOW_ORIGIN_HEADER：后端未设置时，Access-Control-Allow-Origin 头的值（例如 "*" 允许所有源）。
• DEFAULT_MU_AUTH_ALLOWED_GROUPS_HEADER：会话尚无访问权限时使用的默认 Mu-Auth-Allowed-Groups 字符串（例如 "[{\"variables\":[],\"name\":\"public\"}]"）。
• MU_SECRET_KEY_BASE：至少 64 字节的基础字符串，用于生成密钥，生产环境需设置以避免冲突。
• MU_ENCRYPTION_SALT：与 MU_SECRET_KEY_BASE 一起生成用于加密/解密 cookie 的密钥，生产环境需设置以确保会话在标识符重启后保持有效。
• MU_SIGNING_SALT：与 MU_SECRET_KEY_BASE 一起生成用于签名/验证 cookie 的密钥，生产环境需设置以确保会话在标识符重启后保持有效。
• LOG_INCOMING_ALLOWED_GROUPS：设为 "true"、"yes"、"1" 或 "on" 时，记录入站请求中的允许组。
• LOG_OUTGOING_ALLOWED_GROUPS：设为 "true"、"yes"、"1" 或 "on" 时，记录出站响应中的允许组。
• LOG_ALLOWED_GROUPS：设为 "true"、"yes"、"1" 或 "on" 时，同时记录入站和出站允许组。
• LOG_SESSION：设为 "true"、"yes"、"1" 或 "on" 时，记录会话 ID（创建和保留的）。
• SESSION_COOKIE_SECURE：设置会话 cookie 的 SECURE 标志（详见 MDN）。
• SESSION_COOKIE_HTTP_ONLY：设置会话 cookie 的 HTTP_ONLY 标志（详见 MDN），默认启用。
• SESSION_COOKIE_SAME_SITE：设置会话 cookie 的 SAME_SITE 标志（详见 MDN），默认 "Lax"；若 DEFAULT_ACCESS_CONTROL_ALLOW_ORIGIN_HEADER 为 "*"，默认 "None"（此时 cookie 仅在跨域场景可用）。

特殊头

向后端传递 Mu-Session-Id

标识符为每个浏览器代理生成唯一 URI，通过 Mu-Session-Id 头传递给后端。后端微服务可使用该值在存储中关联用户会话数据。

从后端接收 Mu-Auth-Allowed-Groups

最后接收的 Mu-Auth-Allowed-Groups 被视为用户当前的访问权限。后端返回 "Clear" 时，标识符会清除缓存的权限，后续请求不向后端提供 Mu-Auth-Allowed-Groups，触发后端重新计算权限。

从后端接收 Cache-Control

若后端未提供 Cache-Control 头或头包含 no-cache，标识符会发送以下头：

cache-control: no-cache
pragma: no-cache
expires: -1