本文使用「署名 4.0 国际 (CC BY 4.0)」许可协议，欢迎转载、或重新修改使用，但需要注明来源。 [署名 4.0 国际 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/deed.zh)

本文作者: 苏洋

创建时间: 2026年05月30日
统计字数: 7840字
阅读时间: 16分钟阅读
本文链接: https://soulteary.com/2026/05/30/warden-maintainable-access-roster-from-shared-password.html

-----


# Warden（守望者）：从共享口令，到一份可维护的准入名册

Warden（守望者）是一个轻量的准入名单数据服务。

它负责维护“谁可以登录”，以及这些人对应的邮箱、手机号、用户 ID、状态、角色和权限范围等信息。它可以接在 Stargate 后面，作为认证入口背后的准入名册；也可以独立运行，给内部网关、平台、脚本或其他系统提供统一的用户查询能力。

## 写在前面

上一篇里，我们聊了 Stargate。

它负责把认证逻辑前移到网关侧，让反向代理先替我们拦住请求，而不是让每个内部服务都重复实现登录、鉴权、跳转和会话判断。这一步解决的是一个很基础的问题：

> 有没有登录？

但门装上之后，很快会遇到下一个问题：

> 谁可以通过这道门？

一开始，用共享口令就够了。给 Stargate 配一个密码，知道密码的人能进，不知道密码的人进不来。对 HomeLab、测试环境、小团队内部工具，或者几个临时服务来说，这个方案很轻，也很容易跑通。

> 这没什么问题。

很多内部服务一开始都应该这么做。先把门装上，比继续裸奔要好得多。

但只要使用的人多起来，共享口令就开始变得不那么舒服。有人离开项目之后，要不要换密码？如果换密码，是不是所有还在使用的人都要一起更新？如果密码被复制到聊天记录、脚本、配置文件里，又该怎么算？

更麻烦的是，共享口令只能证明一件事：

> 这个人知道密码。

但它证明不了另一件事：

> 这个人是谁？他现在还应该被允许登录吗？

当问题走到这里，就不能只靠一串密码了。你需要一份名单。

这份名单不一定要很复杂。它可以先从一个本地 JSON 文件开始，里面写着谁可以登录，对应的邮箱、手机号、用户 ID、状态、角色和权限范围是什么。但它应该是独立的，可以被 Stargate 查询，也可以被其他内部系统查询；可以先用本地文件维护，后面再接远程数据源、Redis、多实例和监控。

我不希望 Stargate 变成用户数据库。

Stargate 应该继续做入口、会话和登录流程。用户是谁、现在还能不能进、验证码应该发到哪里，这些信息可以单独放到另一个地方。

这就是 Warden 想解决的事情。

它不是完整 IAM，也不想替代公司里的 SSO、LDAP、OIDC 或身份中台。它只先做好一件小事：

**维护一份可以被机器稳定查询的准入名册。**

![soulteary/warden](https://attachment.soulteary.com/2026/05/30/warden-github.jpg)

开源项目地址：[https://github.com/soulteary/warden](https://github.com/soulteary/warden)

如果 Stargate 是先把门装上，那么 Warden 做的事情，就是让这道门不要只认一把共享钥匙，**让它开始认人。**

## 共享口令的问题是怎么出现的

很多内部服务最早的认证方式，都是从一个共享口令开始的。这没什么问题，尤其是在 HomeLab、测试环境和小团队内部工具里，共享口令很适合做第一步。

它不需要数据库、账号系统和注册流程，也不需要接入复杂的身份服务。只要准备一个密码，再把入口保护起来，服务就可以先安全一点地跑起来。

这也是我在做 Stargate 时比较在意的事情：

> 先把门装上。

很多时候，第一步不应该太重。如果一开始就要求接 SSO、配回调、建用户表、发验证码、接短信邮件服务，那很多内部小工具最后大概率还是继续裸奔。

所以，共享口令不是问题。

**长期只靠共享口令，才是问题。**

当服务只有你自己用，或者只有两三个人临时用一下，共享口令足够简单。但只要使用时间拉长，使用的人变多，它的边界就会慢慢出现。

第一个问题，是换密码很麻烦。有人离开项目之后，要不要换密码？如果换，所有还在使用的人都要一起更新；如果不换，这个密码就会变成一把一直流转在外面的钥匙。

第二个问题，是你很难知道密码到底流到哪里去了。它可能在聊天记录里，可能在某个脚本里，可能在浏览器密码管理器里，也可能被复制到某个临时文档、部署说明或者 `.env` 文件里。一旦它扩散出去，你很难再把它完整收回来。

第三个问题，是共享口令没有“人”的概念。它只能回答一个很粗的问题：

> 这个请求里带来的密码对不对？

但它回答不了更多后续问题：

- 这个人是谁；
- 他现在还在不在项目里；
- 他应该看到哪些服务；
- 验证码应该发到哪个邮箱或手机号；
- 下游服务能不能知道他的角色。

这些问题不是共享口令擅长回答的。因为共享口令本质上只是一把钥匙，谁拿到这把钥匙，谁就能开门。

但真实的访问控制，很多时候并不是只看钥匙。你还会关心拿钥匙的人是谁，他现在是否还应该拿着这把钥匙，他的状态是不是正常，他能不能继续走后面的登录流程。

当问题走到这一步，就需要把“密码”往后退一步，把“人”放到前面来。

这时候，我们需要的不是更长的共享口令，也不是把更多用户信息塞进 Stargate 的环境变量里。我们需要一份名单，一份可以被系统查询的名单。

它不一定复杂。一开始甚至可以只是一个 JSON 文件。但这份名单应该能回答几个基础问题：

- 这个邮箱在不在；
- 这个手机号对应谁；
- 这个用户现在是不是 `active`；
- 他有没有 `user_id`；
- 后续验证码应该发到哪里；
- 下游服务需要的话，能不能拿到 `role` 和 `scope`。

这就是 Warden 要补上的那一块，Stargate 负责把门装上，Warden 负责告诉这道门：**谁还应该被允许通过。**

## 以前通常怎么解决

遇到“谁可以登录”这个问题，常见做法大概有几种。

**第一种，是继续把名单写在认证入口里。**

比如把允许登录的邮箱、手机号、用户状态，直接写进 Stargate 的配置里。用户很少的时候，这样当然能用。两三个人、几个测试账号、一两个内部服务，放在环境变量或者配置文件里都不算麻烦。

但这个做法很容易越走越偏。一开始只是加几个邮箱，后来要加手机号，再后来要区分用户状态，接着又想返回 `user_id`、`role`、`scope`，让下游服务也能知道当前用户是谁。再往后，可能还想接远程数据源、做缓存、做同步、做审计。

到这一步，认证入口就不再只是认证入口了。它会慢慢变成半个用户数据库。

这不是我希望 Stargate 走的方向。

Stargate 应该继续守入口、管会话、处理登录流程，而不是把所有用户资料都塞进自己身体里。

**第二种，是每个服务自己维护一份用户列表。**

这也很常见。Grafana 有一份，文档站有一份，内部后台有一份，测试系统有一份，自动化脚本里可能还有一份。

如果这些系统本来就有自己的用户体系，这没什么问题。但很多内部工具并不是这样。它们只是被放在同一个内部环境里，临时给一组人使用。

这时每个服务都维护一份名单，就会出现很现实的麻烦：加一个人，要改很多地方；禁用一个人，也要改很多地方；有的地方改了，有的地方忘了改。最后你很难回答一个简单问题：

> 这个人到底还能访问哪些东西？

名单一旦散在各处，真正麻烦的不是“添加用户”，而是“确认一个人已经被完整移除”。这件事靠人肉检查，很容易漏。

**第三种，是用表格或文档维护名单。**

这可能是很多团队最自然的做法。一个表格里写着邮箱、手机号、备注、所属项目、是否还在使用。人看起来很清楚，编辑起来也方便。

如果只是管理流程，表格很好。但如果它开始参与登录流程，问题就来了。

**表格适合人看，不适合系统在运行时依赖。**

你当然可以把表格作为数据源，比如定期导出成 JSON，或者通过内部接口同步到某个服务。但认证流程本身不应该靠人手复制粘贴，也不应该在登录时临时去翻一个文档。

登录链路需要的是稳定、可查询、可控制返回字段的接口。

不是一个“大家记得去更新”的共享文档。

**第四种，是直接接入完整身份系统。**

比如公司 SSO、LDAP、OIDC、IAM，或者 Keycloak、Authentik、Authelia 这类更完整的身份方案。

如果你已经有这些东西，并且它们已经稳定服务于团队，那当然应该优先使用它们。完整身份系统能处理的问题更多：用户生命周期、组织架构、权限策略、多因素认证、单点登录、审计、协议兼容，这些都不是一个轻量小工具应该重新发明的东西。

但很多内部服务遇到的问题，并没有一开始就到这个规模。你可能只是有几个 HomeLab 服务、几个测试面板、一个内部文档站、一组临时工具，或者一个还没确定会不会长期使用的小平台。

为了这些东西第一天就接完整 IAM，有时会显得太重。不是能力不好，而是启动成本太高。

你可能要准备数据库、回调地址、证书、邮件服务、管理员账号、用户导入、策略配置，还要让每个服务都理解这套登录方式。最后很容易变成：明明只是想把几个人的访问控制住，却先搭了一整套身份中台。

所以，我想要的是一个中间方案。

它不把用户资料继续塞进认证入口里，也不要求每个服务自己维护一份名单；它可以从本地文件开始，也可以后面再接远程系统。它不负责完整身份治理，不负责登录页面，不负责发送验证码，也不负责校验 OTP。

它**只**先做好一件事：维护一份可以被系统查询的准入名册。

这份名单可以很小，也可以慢慢变大。一开始，它只是一个 `data.json`。后面，它可以接远程 API、Redis、多实例、监控和审计。

但不管后面怎么变，它回答的问题都很具体：

- 这个人，在不在名单里？
- 他现在是不是 `active`？
- 后面的登录流程，应该继续，还是停在这里？

这就是 Warden 想站立的位置。

## 为什么要把名单单独拆出来

做到这里，其实会有一个很自然的选择：

既然 Stargate 已经站在入口前面了，那能不能直接让 Stargate 维护这份名单？

当然可以。

如果只是几个人、几个邮箱、几个手机号，把它们写进 Stargate 的配置里，并不是不能用。甚至在最早期，这样可能还更省事。

但，我不太想让 Stargate 往这个方向长。

因为一旦认证入口开始维护用户资料，它很快就会多出很多原本不属于自己的事情。比如用户的邮箱是什么，手机号是什么，`user_id` 是什么，现在是不是 `active`，`role` 和 `scope` 要不要返回给下游服务，名单来自本地文件还是远程系统。如果远程系统挂了，要不要回退到本地数据？多个来源里同一个用户冲突了，又应该以谁为准？

这些问题看起来都和“登录”有关，但它们其实不是入口认证本身。

Stargate 真正要做的事情，是守在门口。它应该关心请求有没有登录、会话是不是有效、没有登录时要不要跳转登录页、API 请求要不要返回 401、登录完成后怎么把用户带回原来的服务。

这些事情已经足够具体了。

如果再把用户资料、名单同步、状态判断、字段过滤、远程数据源、缓存和合并策略都塞进去，Stargate 会变得越来越重。最后它就不再只是一个入口认证网关，而会变成半个用户系统。

这不是我想要的方向。

所以我把“名单”这件事单独拆了出来。Warden 只关心一件事：**谁在准入名单里。**

它不负责展示登录页，不负责签发会话，不负责发送验证码，不负责校验 OTP，也不打算替代完整 IAM。它要做的是更小的一块：从某个地方拿到用户数据，把这份数据整理好，然后提供一个稳定的查询接口。

调用方可以问它几个很具体的问题：

- 这个邮箱在不在；
- 这个手机号对应谁；
- 这个 `user_id` 是否存在；
- 这个用户现在是不是 `active`；
- 后续验证码应该发到哪里；
- 如果下游服务需要，能不能拿到 `role` 和 `scope`。

Warden 回答这些问题。

至于拿到答案之后，要不要继续登录、要不要发验证码、要不要创建会话，那是调用方的事情。

这样拆开以后，后面替换数据源、验证码通道和入口逻辑时，都不需要互相牵连。

- Stargate 负责守入口。
- Warden 负责管名单。
- Herald 负责送验证码。

这个分工不是为了把系统拆得更复杂，恰恰相反，是为了让每一块都不要长得太快。Stargate 不需要知道名单到底来自哪里，Warden 不需要知道登录页长什么样，Herald 也不需要判断谁有资格登录。每个服务只把自己的事情做好，后面替换起来也会更容易。

比如，一开始你可以让 Warden 只读本地 `data.json`。等名单变多了，再把不同团队拆成多个 JSON 文件。再往后，如果已经有内部用户系统，可以让 Warden 去同步远程数据。如果服务变多了，再加 Redis、缓存、多实例和监控。

这些变化都不应该影响 Stargate 的入口逻辑。

同样，后面如果验证码通道从邮件换成短信，或者从某个服务商换到另一个服务商，也不应该影响 Warden 的数据来源。

**这就是拆开的好处。**

不是每个小工具都要做成平台，也不是每个内部服务都需要完整身份中台。很多时候，我们只是需要在共享口令和完整 IAM 之间，补上一个很薄、但能长期维护的中间层。

Warden 就是这个中间层。

它可以接在 Stargate 后面，也可以独立给其他系统用。内部网关可以查它，脚本可以查它，平台可以查它，验证码服务也可以查它。

只要你的问题是：这个邮箱、手机号或 `user_id`，现在还允不允许继续往下走？那么，Warden 就可以站在这里，先把这件事回答清楚。

## Warden 是怎么工作的

Warden 的工作方式很直接：你给它一份用户数据，它把这份数据加载起来，然后通过 HTTP API 对外提供查询能力。

调用方可以用邮箱、手机号或用户 ID 来问它：这个人是不是在名单里？他现在是什么状态？后续验证应该发到哪里？如果下游服务需要，能不能拿到他的 `user_id`、`role` 和 `scope`？

Warden 不负责决定整个登录流程。

它只是把准入名单这部分信息整理好，稳定地返回给调用方。至于拿到结果之后，是继续发验证码，还是直接拒绝登录，还是写入会话，那是 Stargate、Herald 或其他调用方要做的事情。

最小的数据文件可以很简单：

```json
[
  {
    "phone": "13800138000",
    "mail": "admin@example.com"
  }
]
```

这已经能回答一个基础问题：

> 这个手机号或邮箱，在不在名单里？

但真实使用时，我更建议至少把 `user_id` 和 `status` 写上。

比如：

```json
[
  {
    "phone": "13800138000",
    "mail": "admin@example.com",
    "user_id": "admin-001",
    "status": "active"
  }
]
```

这样 Warden 就不只是一个联系方式列表，而是开始变成一份真正的准入名册。

稍微完整一点的数据，可以继续加上角色、权限范围和显示名称：

```json
[
  {
    "phone": "13800138000",
    "mail": "admin@example.com",
    "user_id": "admin-001",
    "status": "active",
    "scope": ["read", "write", "admin"],
    "role": "admin",
    "name": "管理员"
  },
  {
    "phone": "13900139000",
    "mail": "user@example.com",
    "user_id": "user-001",
    "status": "active",
    "scope": ["read"],
    "role": "user",
    "name": "普通用户"
  }
]
```

这里最重要的字段，是 `status`。

很多时候，名单里有没有这个人，和这个人现在能不能继续登录，不完全是一回事。

比如，一个人曾经在项目里，后来离开了。你可以直接把他从名单里删掉，但有时候，保留记录会更方便排查问题。这时就可以把状态从：

```json
{
  "mail": "user@example.com",
  "status": "active"
}
```

改成：

```json
{
  "mail": "user@example.com",
  "status": "inactive"
}
```

或者：

```json
{
  "mail": "user@example.com",
  "status": "suspended"
}
```

这样调用方看到的就不是一个模糊的“查不到用户”，而是一个更明确的结果：

> 这个人存在，但现在不应该继续登录。

这对排查问题很有用，也比直接删除更容易留下管理痕迹。

作为独立服务时，Warden 的流程大概是这样：

```Text
调用方拿到邮箱、手机号或 user_id
    ↓
调用 Warden 查询用户
    ↓
Warden 在准入名单里查找对应用户
    ↓
Warden 返回用户状态、联系方式和基础身份信息
    ↓
调用方根据返回结果决定后续动作
```

如果只是给某个内部脚本或平台使用，这个流程已经够了。

脚本可以问：

```Text
admin@example.com 是否在名单里？
```

内部平台可以问：

```Text
这个 user_id 对应的角色是什么？
```

验证码服务可以问：

```Text
后续验证码应该发到邮箱，还是手机号？
```

这些问题都可以通过同一份名单回答。

如果 Warden 接在 Stargate 后面，流程会更像这样：

```Text
用户访问受保护服务
    ↓
Stargate 发现用户还没有登录
    ↓
用户输入邮箱或手机号
    ↓
Stargate 调用 Warden 查询用户
    ↓
Warden 返回用户是否存在、当前状态和联系方式
    ↓
Stargate 判断是否继续后续登录流程
```

通常来说，只有用户存在，并且状态是 `active` 时，登录流程才应该继续。如果用户不存在，流程应该停下来；如果用户存在，但状态是 `inactive` 或 `suspended`，也不应该继续发验证码。

这件事不应该靠共享口令来判断，也不应该靠人工确认。

它应该变成登录流程里一次稳定的机器查询。

如果后面再接 Herald，流程会再多一步：

```Text
用户访问受保护服务
    ↓
Stargate 发现用户还没有登录
    ↓
用户输入邮箱或手机号
    ↓
Stargate 调用 Warden 查询用户
    ↓
Warden 返回用户状态和联系方式
    ↓
Stargate 判断用户是否允许继续
    ↓
允许继续：Stargate 调用 Herald 发送验证码
    ↓
用户输入验证码
    ↓
Stargate 完成会话
```

这个过程里，Warden 仍然只负责名单和状态。后续要不要发验证码、怎么创建会话，都交给调用方继续处理。

这样拆开以后，后面调整起来会轻很多。

比如，用户数据一开始来自本地 `data.json`，后来你想接远程 API，再后来你想接 Redis、缓存和多实例，这些变化主要发生在 Warden 里。Stargate 不需要知道名单到底从哪里来。

同样，如果验证码以后从邮件换成短信，或者从一个服务商换成另一个服务商，也主要是 Herald 的事情。Warden 仍然只需要返回联系方式和状态。

这就是我希望 Warden 保持的边界。

它不是登录系统，不是验证码系统，也不是完整身份中台。它只是在认证链路里，把原来最容易散落在配置、表格、脚本和聊天记录里的那部分东西，收成一份可以被机器查询的名单。

先让系统知道：**谁是这个人。**

以及，他现在还能不能继续往下走。

## 用 Docker Compose 快速跑起来

理解了 Warden 的工作方式之后，我们先把它跑起来。

这一节，我们先不接 Stargate，不接 Herald，不接远程 API，也不启用 Redis。只做一件事：

让 Warden 能从本地文件里加载一份名单，然后回答“这个人是不是在名单里”。

先创建一个 `data.json`：

```bash
cat > data.json <<EOF
[
  {
    "phone": "13800138000",
    "mail": "admin@example.com",
    "user_id": "admin-001",
    "status": "active",
    "scope": ["read", "write", "admin"],
    "role": "admin",
    "name": "管理员"
  },
  {
    "phone": "13900139000",
    "mail": "user@example.com",
    "user_id": "user-001",
    "status": "active",
    "scope": ["read"],
    "role": "user",
    "name": "普通用户"
  }
]
EOF
```

这份文件里只有两个用户：第一个是管理员，第二个是普通用户。它们都有手机号、邮箱、用户 ID 和状态。

第一次跑起来时，重点不是把用户模型一次性想完整，而是确认 Warden 能正常加载数据、保护接口、返回查询结果。所以字段不用一开始就设计得太复杂，先让最短链路跑通。

接着创建 `compose.yaml`：

```yaml
services:
  warden:
    image: ghcr.io/soulteary/warden:latest
    container_name: warden
    restart: unless-stopped

    ports:
      - "8081:8081"

    environment:
      - PORT=8081
      - MODE=ONLY_LOCAL
      - DATA_FILE=/app/data.json
      - REDIS_ENABLED=false
      - API_KEY=your-secret-api-key-here
      - RESPONSE_FIELDS=user_id,mail,phone,status,scope,role,name

    volumes:
      - ./data.json:/app/data.json:ro
      - /etc/localtime:/etc/localtime:ro

    healthcheck:
      test: ["CMD-SHELL", "wget --quiet --tries=1 --spider http://localhost:8081/health || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 10s
```

这里为了本地演示，直接把 `8081` 端口映射到了宿主机。

真实部署时，不建议把 Warden 直接暴露到公网。更合适的方式，是让它只跑在内部网络里，由 Stargate、内部网关或其他可信调用方访问。这里先映射端口，只是为了方便本地用 `curl` 验证。

这段配置里，第一次需要看懂的配置不多。

```yaml
- MODE=ONLY_LOCAL
```

表示只使用本地数据文件，也就是刚才创建的 `data.json`。

```yaml
- DATA_FILE=/app/data.json
```

表示 Warden 在容器里从这个路径读取用户数据。前面的 `volumes` 已经把本地的 `./data.json` 挂载到了这个位置。

```yaml
- REDIS_ENABLED=false
```

表示这个最小示例先不启用 Redis。本地文件、单实例、少量用户的场景里，先禁用它更容易排查问题。

```yaml
- API_KEY=your-secret-api-key-here
```

表示查询用户数据时需要带上 API Key。Warden 管的是准入名单，不应该让任何人都能直接查。即使只是本地测试，也建议从第一天就把 API Key 带上。

```yaml
- RESPONSE_FIELDS=user_id,mail,phone,status,scope,role,name
```

表示接口只返回这些字段。这个配置不是本地测试必须的，但我建议早点用起来。Warden 后面会越来越像一份内部身份目录，字段能少给就少给。

确认文件准备好之后，启动服务：

```bash
docker compose up -d
```

先看容器状态：

```bash
docker compose ps
```

如果服务正常，再看健康检查：

```bash
curl http://localhost:8081/health
```

正常情况下，会看到类似这样的结果：

```json
{
  "status": "ok",
  "details": {
    "redis": "disabled",
    "data_loaded": true,
    "user_count": 2
  },
  "mode": "ONLY_LOCAL"
}
```

这里重点看两个字段：`data_loaded` 是 `true`，说明本地名单已经加载成功；`user_count` 是 `2`，说明刚才写入的两个用户都被 Warden 读到了。

健康检查通过之后，再查一下完整名单：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8081/
```

也可以查看当前合并后的 `data.json`：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8081/data.json
```

这两个接口更适合排查数据是否加载正确。真实登录流程里，一般不会频繁拉完整名单，更多时候只需要查一个具体的人。

比如按邮箱查询：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/user?mail=admin@example.com"
```

按手机号查询：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/user?phone=13800138000"
```

或者按用户 ID 查询：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/user?user_id=admin-001"
```

如果后面准备接 Stargate、Herald 或其他登录流程，更建议先看这个接口：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/v1/lookup?identifier=admin@example.com"
```

`identifier` 可以是邮箱、手机号或用户 ID。返回结果大概会像这样：

```json
{
  "user_id": "admin-001",
  "destination": {
    "email": "admin@example.com",
    "phone": "13800138000"
  },
  "status": "active",
  "channel_hint": "sms",
  "name": "管理员"
}
```

这里的 `destination` 是后续验证流程可能用到的联系方式。如果用户有手机号，`channel_hint` 可以提示后续流程优先走短信；如果只有邮箱，就可以走邮件。

当然，Warden 本身不负责发送验证码。

它只是把“这个人是谁、状态是什么、后续应该联系哪里”这几件事返回给调用方。

到这里，Warden 的最小链路就跑通了。我们已经验证了几件事：

```Text
Warden 能正常启动
Warden 能加载本地 data.json
Warden 能通过 API Key 保护查询接口
Warden 能按邮箱、手机号或 user_id 查到用户
Warden 能给登录流程返回 lookup 结果
```

这一步完成后，先不要急着接远程数据源，也不要急着上 Redis，更不要一上来就把所有服务都接进来。

我更建议先把这个最小示例跑顺。

可以改一下 `data.json`，加一个用户，把某个用户的 `status` 从 `active` 改成 `inactive`，再查一次 `/v1/lookup`。确认自己理解 Warden 怎么读数据、怎么返回状态之后，再继续接 Stargate。

基础设施工具最好一步一步来。

先让名单能被稳定查询，再让入口服务依赖这份名单。

## 常用配置说明

Warden 的配置方式比较灵活，可以用命令行参数，也可以用环境变量，还可以用配置文件。不过第一次使用时，不需要把所有配置都看完。

我建议先把配置分成两组。

第一组，是第一天就会用到的配置：

```Text
API_KEY
DATA_FILE / DATA_DIR
MODE
RESPONSE_FIELDS
```

第二组，是后面接远程数据源、多实例和长期运行时再看的配置：

```Text
CONFIG / KEY
REDIS_ENABLED / REDIS
PORT
```

这样拆开以后，配置会好理解很多。先让本地文件、API Key 和查询接口跑通，再去考虑远程数据源、Redis、多实例和监控。

### `API_KEY`：先把查询接口保护起来

Warden 管的是准入名单。这份名单里可能有邮箱、手机号、用户 ID、角色、权限范围，后面还可能有更多内部字段，所以它不应该裸着给人查。

最小示例里也建议设置：

```bash
API_KEY=your-secret-api-key-here
```

查询时带上：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8081/
```

也可以使用 Bearer 形式：

```bash
curl -H "Authorization: Bearer your-secret-api-key-here" \
  http://localhost:8081/
```

本地测试时，示例密钥只是为了方便演示。但只要进入真实环境，就不要继续用这种占位值，也不要把 `API_KEY` 写进仓库。

Warden 本身不负责登录页面，也不签发会话，但它会回答“谁可以继续往下走”。这类接口从第一天开始就应该被保护起来。

### `DATA_FILE`：从一个本地文件开始

最简单的数据来源，就是一个本地 JSON 文件。

默认可以从当前目录的 `data.json` 开始：

```bash
DATA_FILE=./data.json
```

在 Docker Compose 里，一般会把本地文件挂载进容器：

```yaml
volumes:
  - ./data.json:/app/data.json:ro
```

如果想写得更明确，也可以直接指定容器里的路径：

```yaml
environment:
  - DATA_FILE=/app/data.json
```

本地文件很适合 Warden 的第一步。数据量不大、变更不频繁、使用的人也不多时，一个 `data.json` 已经足够好用。

它的好处是直观。你能很清楚地看到名单里有哪些人，每个人的邮箱、手机号、状态、角色和权限范围是什么。调试时也简单，改完文件，重启服务，重新查一次接口，就能确认结果。

这比一开始就接远程 API、缓存、多实例要轻很多。

### `DATA_DIR`：名单变长之后再拆开

等用户多起来之后，一个 `data.json` 可能会变得不太好维护。这时可以把名单拆成多个文件。

比如：

```Text
data/
  admin.json
  team-a.json
  team-b.json
  readonly-users.json
```

然后配置：

```bash
DATA_DIR=/app/data
```

Warden 会读取这个目录下的数据文件，并把它们合并成一份可以查询的名单。

这个方式很适合把管理员和普通用户分开维护，或者让不同团队各自维护自己的名单。你也可以把手工维护的数据和导出的数据分开放，后面排查问题时会更清楚：

- 这个用户来自哪一份名单；
- 这个状态是谁改的；
- 这个团队是不是已经把离开的成员移除了。

这些问题在一个很长的 JSON 文件里会比较难看出来。拆成目录之后，会好很多。

### `MODE`：先只用本地数据

`MODE` 用来决定 Warden 怎么使用本地数据和远程数据。

第一次使用时，我建议直接用：

```bash
MODE=ONLY_LOCAL
```

也就是只读取本地文件。这最容易理解，也最方便排查问题。等本地文件、API Key、用户查询都跑顺之后，再考虑远程数据源。

常见模式可以先这样理解：

```Text
ONLY_LOCAL
只使用本地文件。

ONLY_REMOTE
只使用远程数据。

REMOTE_FIRST
远程数据优先，本地数据作为补充。

LOCAL_FIRST
本地数据优先，远程数据作为补充。

REMOTE_FIRST_ALLOW_REMOTE_FAILED
远程优先，但远程失败时允许回退到本地数据。

LOCAL_FIRST_ALLOW_REMOTE_FAILED
本地优先，但本地失败时允许回退到远程数据。
```

这些名字看起来有点长，但含义比较直接。如果你只是本地测试，选 `ONLY_LOCAL`。如果已经有一套内部用户系统，Warden 只是同步一份准入名单，可以考虑 `ONLY_REMOTE` 或 `REMOTE_FIRST`。

带 `ALLOW_REMOTE_FAILED` 的模式要谨慎。它会让系统更稳，但也可能带来另一个问题：远程系统里已经禁用的人，本地文件里是不是还存在？如果本地文件没有同步更新，回退时会不会放过不该放过的人？

所以生产环境里，不要只看“可用性”，还要看这份名单是不是仍然可信。

### `RESPONSE_FIELDS`：不要把所有字段都返回出去

默认情况下，如果用户对象里有很多字段，调用方可能会拿到比较完整的数据。这在本地调试时很方便，但真实使用时不一定合适。

比如你的用户数据里可能有一些内部备注：

```json
{
  "mail": "admin@example.com",
  "phone": "13800138000",
  "user_id": "admin-001",
  "status": "active",
  "role": "admin",
  "scope": ["read", "write", "admin"],
  "name": "管理员",
  "source": "manual",
  "note": "临时加入测试环境"
}
```

Stargate 可能只需要知道：

```Text
user_id
mail
phone
status
scope
role
name
```

那就没有必要把 `source`、`note` 或其他内部字段都返回出去。可以用 `RESPONSE_FIELDS` 控制返回字段：

```bash
RESPONSE_FIELDS=user_id,mail,phone,status,scope,role,name
```

这个配置很容易被忽略，但我建议尽早用起来。因为 Warden 的数据会越来越像一份内部身份目录，一旦调用方变多，字段暴露就应该收紧。

让每个调用方只拿到自己需要的字段，比“先全给出去，后面再收回来”要好很多。

### `CONFIG` 和 `KEY`：接远程数据源

如果名单不再适合手工维护，或者你已经有内部用户系统，可以让 Warden 从远程接口读取用户数据。

比如：

```bash
CONFIG=https://example.com/api/users.json
```

如果远程接口需要认证，可以加上：

```bash
KEY=Bearer your-token-here
```

远程接口返回的数据格式，应该和本地 `data.json` 保持一致，也就是一组用户对象：

```json
[
  {
    "mail": "admin@example.com",
    "phone": "13800138000",
    "user_id": "admin-001",
    "status": "active",
    "scope": ["read", "write", "admin"],
    "role": "admin"
  }
]
```

这样 Warden 不需要关心数据到底来自哪里。本地文件也好，远程 API 也好，最后都整理成同一份准入名单。

这也是把名单单独拆出来的好处。Stargate 不需要知道用户数据是手写的，还是从远程系统同步的。它只需要问 Warden：

这个人现在能不能继续往下走？

不过，远程数据源进入生产环境时要多注意几件事：尽量使用 HTTPS，远程接口需要认证，不要把 Token 写进仓库，不要跳过 TLS 校验，也不要把远程数据源指向不可信地址。

Warden 是认证链路里的一环。它的数据源如果不可信，后面的登录流程也就不可信了。

### `REDIS_ENABLED` 和 `REDIS`：后面再考虑多实例

最小使用时，可以先禁用 Redis：

```bash
REDIS_ENABLED=false
```

如果只是一个 Warden 实例，读本地文件，用户数量也不多，先不用 Redis 会更容易排查问题。

等 Warden 开始长期运行，或者你准备做多实例部署时，再考虑打开：

```bash
REDIS_ENABLED=true
REDIS=warden-redis:6379
```

Redis 主要用于缓存、分布式锁和多实例场景。它不是第一天必须要有的东西，但当 Warden 变成多个服务都会依赖的准入名册时，它会让同步、缓存和实例之间的协调更稳一些。

这里还是同一个原则：**先让最短链路跑通，再让它跑得更稳。**

### `PORT`：通常不用改

Warden 默认监听 `8081`。

```bash
PORT=8081
```

本地测试时，保持默认即可。如果你的环境里这个端口已经被占用，或者你想和其他服务统一端口规划，再改它。

比如：

```bash
PORT=18081
```

在 Docker Compose 里，也要同步调整映射关系：

```yaml
ports:
  - "18081:18081"

environment:
  - PORT=18081
```

不过真实部署时，我更建议不要太依赖宿主机端口暴露。Warden 更适合跑在内部网络里，让 Stargate、内部网关或可信调用方通过服务名访问。

比如在同一个 Compose 网络里，Stargate 可以直接访问：

```Text
http://warden:8081
```

这样就不需要把 Warden 暴露给外部访问者。

### 一个更完整一点的配置示例

如果只是本地文件起步，配置可以保持很小：

```yaml
environment:
  - PORT=8081
  - MODE=ONLY_LOCAL
  - DATA_FILE=/app/data.json
  - REDIS_ENABLED=false
  - API_KEY=your-secret-api-key-here
  - RESPONSE_FIELDS=user_id,mail,phone,status,scope,role,name
```

如果后面改成远程数据源，可以变成：

```yaml
environment:
  - PORT=8081
  - MODE=REMOTE_FIRST_ALLOW_REMOTE_FAILED
  - DATA_FILE=/app/data.json
  - CONFIG=https://example.com/api/users.json
  - KEY=Bearer your-token-here
  - REDIS_ENABLED=false
  - API_KEY=your-secret-api-key-here
  - RESPONSE_FIELDS=user_id,mail,phone,status,scope,role,name
```

如果再往后需要多实例和缓存，可以继续加 Redis：

```yaml
environment:
  - PORT=8081
  - MODE=REMOTE_FIRST_ALLOW_REMOTE_FAILED
  - DATA_FILE=/app/data.json
  - CONFIG=https://example.com/api/users.json
  - KEY=Bearer your-token-here
  - REDIS_ENABLED=true
  - REDIS=warden-redis:6379
  - API_KEY=your-secret-api-key-here
  - RESPONSE_FIELDS=user_id,mail,phone,status,scope,role,name
```

但，我不建议一开始就用最后这一版。

第一次跑 Warden，最重要的是确认三件事：

```Text
数据能不能加载
接口能不能查询
返回结果是不是你预期的那个人
```

这些都确认之后，再去考虑远程数据、Redis、多实例和监控。配置不是越多越好，能解释清楚每一项为什么存在，才比较重要。

## 作为独立服务怎么用

Warden 不一定要接在 Stargate 后面。它本身也可以作为一个很小的准入数据服务，给内部系统使用。

比如，你有一个内部网关，需要判断某个邮箱能不能访问；或者有一个自动化脚本，需要确认某个手机号是不是还在允许名单里；又或者有一个内部平台，只想从统一的地方拿到用户的 `user_id`、`role` 和 `scope`。

这些场景里，Warden 都可以独立工作。

它不关心调用方是不是 Stargate。只要调用方能带着 API Key 来查，它就负责回答几个问题：

- 这个人是不是在名单里；
- 这个人现在是什么状态；
- 后续流程需要联系他时，应该用邮箱还是手机号；
- 下游系统需要用户信息时，能不能拿到稳定的 `user_id`。

常用接口其实不多。

### 查询当前名单

如果你想看 Warden 当前加载出来的完整名单，可以访问根路径：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8081/
```

也可以访问合并后的 `data.json`：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8081/data.json
```

这两个接口更适合排查数据。比如你刚改完本地文件，或者刚接入远程数据源，想确认 Warden 最终看到的名单是什么样。

如果用户数量比较多，也可以分页查询：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/?page=1&page_size=100"
```

不过真实登录流程里，一般不会频繁拉完整名单。更多时候，调用方只需要查一个具体的人。

### 查询单个用户

Warden 支持按手机号、邮箱或用户 ID 查询用户。

按手机号查：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/user?phone=13800138000"
```

按邮箱查：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/user?mail=admin@example.com"
```

按用户 ID 查：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/user?user_id=admin-001"
```

这个接口适合内部系统做精确查询。比如内部平台已经知道当前用户的邮箱，只想查他的 `role` 和 `scope`；或者某个脚本拿到了手机号，想确认这个人是不是还在准入名单里。

返回结果里通常会包含用户对象中的字段：

```json
{
  "phone": "13800138000",
  "mail": "admin@example.com",
  "user_id": "admin-001",
  "status": "active",
  "scope": ["read", "write", "admin"],
  "role": "admin",
  "name": "管理员"
}
```

这里需要注意一件事：

查到用户，不等于一定应该继续放行。

调用方还应该看 `status`。一般来说，只有 `active` 状态才应该继续往下走。如果是 `inactive` 或 `suspended`，即使这个人还在名单里，也不应该继续登录或访问。

这也是我建议保留 `status` 字段的原因。它能把“查不到用户”和“用户存在但不允许继续访问”区分开。

### 给登录流程用的 lookup

如果调用方是在做登录流程，推荐使用 `/v1/lookup`。

它的输入更简单：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/v1/lookup?identifier=admin@example.com"
```

`identifier` 可以是邮箱、手机号，也可以是用户 ID。调用方不需要提前判断用户输入的是哪一种。Warden 会尝试在名单里匹配对应用户，然后返回更适合登录流程使用的数据。

比如：

```json
{
  "user_id": "admin-001",
  "destination": {
    "email": "admin@example.com",
    "phone": "13800138000"
  },
  "status": "active",
  "channel_hint": "sms",
  "name": "管理员"
}
```

这里的 `destination` 是后续验证流程可以使用的联系方式。如果用户有手机号，后面可以走短信；如果只有邮箱，后面可以走邮件。`channel_hint` 只是提示后续流程更适合使用哪个通道。

Warden 自己不发送验证码。

它只是把“可以联系到哪里”这件事告诉调用方。

比如 Stargate 可以先调用 Warden，确认这个邮箱是不是在名单里、用户现在是不是 `active`、验证码应该发到哪里。拿到结果之后，再决定要不要继续调用 Herald 发送验证码。

内部平台也可以这样用：确认某个 `user_id` 是否有效，判断用户有没有 `admin` scope，或者在用户状态是 `suspended` 时停止后续流程。

Warden 的价值不在于它有很多接口，而在于这些系统不用再各自维护一份名单。同一个用户，尽量从同一份准入数据里查出来。

### 健康检查

Warden 也提供健康检查接口：

```bash
curl http://localhost:8081/health
```

或者：

```bash
curl http://localhost:8081/healthcheck
```

这类接口适合接入 Docker、Kubernetes、反向代理或监控系统。本地调试时，你可以直接用它确认服务是否启动、数据是否加载。

比如：

```json
{
  "status": "ok",
  "details": {
    "redis": "disabled",
    "data_loaded": true,
    "user_count": 2
  },
  "mode": "ONLY_LOCAL"
}
```

这里重点看 `data_loaded` 和 `user_count`。如果 `data_loaded` 是 `false`，说明数据文件没有正确加载；如果 `user_count` 不符合预期，说明名单内容可能没有被正确读取，或者远程数据源没有按预期返回。

但生产环境里，不建议把健康检查直接暴露给公网。它虽然不是用户查询接口，但仍然可能暴露服务状态、数据加载情况和运行模式。更合适的做法，是只允许内部网络、反向代理或监控系统访问。

### 一个独立使用的小例子

假设你有一个内部脚本，准备在执行敏感操作前确认某个邮箱是否还在准入名单里。它可以先调用：

```bash
curl -s -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/v1/lookup?identifier=admin@example.com"
```

然后检查返回里的 `status`：

```Text
status == active      继续执行
status != active      停止执行
用户不存在            停止执行
```

这样脚本不需要自己维护一份邮箱列表，也不需要知道名单到底来自本地文件，还是远程 API。它只需要问 Warden。

再比如，你有一个内部平台，需要展示当前用户的角色和权限范围。它也可以按邮箱或 `user_id` 查询：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/user?user_id=admin-001"
```

拿到结果后，只使用自己需要的字段：

```json
{
  "user_id": "admin-001",
  "status": "active",
  "role": "admin",
  "scope": ["read", "write", "admin"]
}
```

这时最好配合前面说的 `RESPONSE_FIELDS`。

一个内部脚本可能只需要 `status`，一个登录流程可能只需要 `user_id`、`destination` 和 `status`，一个后端服务可能只需要 `role` 和 `scope`。字段能少给，就少给。

这不是为了把系统做复杂，而是因为 Warden 后面会越来越接近一份内部身份目录。一旦调用方变多，最开始随手返回出去的字段，后面再想收回来就比较麻烦。

所以独立使用 Warden 时，我会把它当成一个很薄的内部能力：它不负责登录，不负责验证码，不负责会话，也不负责复杂权限策略。它只负责让其他系统不用再各自维护一份名单。

大家都问同一个地方：

- 这个人是谁？
- 他现在还能不能继续往下走？

需要的话，应该把哪些基础身份信息交给下游？

## 接到 Stargate 后会变成什么样

前面我们一直把 Warden 当成一个独立服务来看。它能加载名单，能查询用户，能返回状态、联系方式、角色和权限范围。

但如果你已经按照上一篇把 Stargate 跑起来，那么接入 Warden 之后，登录流程会多一个很关键的判断：

这个输入的邮箱、手机号或 `user_id`，是不是还在准入名单里？

上一篇里，Stargate 可以只靠共享口令完成登录。这很轻，也很适合第一步。但它的判断方式比较简单：

```Text
你知道密码吗？
```

接入 Warden 之后，判断方式会变成：

```Text
你是谁？
你在不在名单里？
你现在是不是 active？
后续验证应该发到哪里？
```

这不是把 Stargate 变复杂，而是把原来塞不进共享口令里的那部分信息，交给 Warden 来回答。

原来的流程大概是：

```Text
用户访问受保护服务
    ↓
Stargate 发现用户还没有登录
    ↓
用户输入共享口令
    ↓
口令正确，创建会话
    ↓
回到原来的服务
```

接入 Warden 之后，流程会变成：

```Text
用户访问受保护服务
    ↓
Stargate 发现用户还没有登录
    ↓
用户输入邮箱、手机号或 user_id
    ↓
Stargate 调用 Warden 查询用户
    ↓
Warden 返回用户是否存在、当前状态和联系方式
    ↓
Stargate 根据结果决定是否继续登录流程
```

如果用户不存在，流程应该停下来。如果用户存在，但 `status` 不是 `active`，流程也应该停下来。只有用户存在，并且状态正常，后面才继续做验证、创建会话或进入其他登录步骤。

这样一来，Stargate 仍然负责入口和会话，Warden 只负责回答名单问题。Stargate 不需要自己维护用户数据，也不需要知道名单来自本地文件，还是远程 API。

它只需要在登录流程里问一次 Warden：这个人现在还能不能继续往下走？

### Stargate 侧怎么配置

Stargate 侧启用 Warden，大概需要这些配置：

```bash
WARDEN_ENABLED=true
WARDEN_URL=http://warden:8081
WARDEN_API_KEY=your-secret-api-key-here
WARDEN_CACHE_TTL=300
```

`WARDEN_ENABLED` 表示启用 Warden 查询：

```bash
WARDEN_ENABLED=true
```

不开这个开关时，Stargate 可以继续按原来的共享口令方式工作。打开之后，Stargate 就会在登录流程里增加 Warden 查询。

`WARDEN_URL` 表示 Warden 服务地址：

```bash
WARDEN_URL=http://warden:8081
```

如果 Stargate 和 Warden 在同一个 Docker Compose 网络里，这里通常可以直接使用服务名：

```Text
http://warden:8081
```

不一定需要把 Warden 暴露到宿主机端口。真实部署时，我也更建议这样做。Warden 只给内部服务访问，不直接对公网开放。

`WARDEN_API_KEY` 需要和 Warden 侧的 `API_KEY` 保持一致：

```bash
WARDEN_API_KEY=your-secret-api-key-here
```

也就是说，Warden 里配置的是：

```bash
API_KEY=your-secret-api-key-here
```

Stargate 里配置的是：

```bash
WARDEN_API_KEY=your-secret-api-key-here
```

这两个值不一致时，Stargate 就查不到 Warden。这类问题排查起来很容易绕路，所以第一次接入时，建议先不要同时打开太多能力。先确认 Stargate 能访问 Warden，再确认 API Key 没写错，最后再看用户状态和后续验证流程。

`WARDEN_CACHE_TTL` 用来控制缓存时间：

```bash
WARDEN_CACHE_TTL=300
```

这里的 `300` 通常表示缓存 300 秒（具体缓存行为以 Stargate 当前版本实现为准）。缓存的好处是减少重复查询，比如同一个用户短时间内多次触发登录流程，Stargate 不需要每次都去问 Warden。

但缓存也有代价。如果你刚刚把某个用户从 `active` 改成 `inactive`，Stargate 可能会在缓存过期前继续使用旧结果。所以这个值不要随手设得太长。内部测试环境可以稍微宽松一点，对准入变更比较敏感的环境，缓存时间就应该短一些，甚至先关掉缓存做验证。

### 一个简单的组合示例

如果把 Stargate 和 Warden 放在同一个 Compose 项目里，结构可以类似这样：

```yaml
services:
  stargate:
    image: soulteary/stargate:latest
    container_name: stargate
    restart: unless-stopped

    environment:
      - AUTH_HOST=auth.test.localhost
      - LANGUAGE=zh

      - WARDEN_ENABLED=true
      - WARDEN_URL=http://warden:8081
      - WARDEN_API_KEY=your-secret-api-key-here
      - WARDEN_CACHE_TTL=300

    networks:
      - proxy
      - auth-internal

    labels:
      - traefik.enable=true
      - traefik.docker.network=proxy

      - traefik.http.routers.stargate.entrypoints=http
      - traefik.http.routers.stargate.rule=Host(`auth.test.localhost`) || Path(`/_session_exchange`)
      - traefik.http.routers.stargate.service=stargate

      - traefik.http.services.stargate.loadbalancer.server.port=80

      - traefik.http.middlewares.stargate.forwardauth.address=http://stargate/_auth
      - traefik.http.middlewares.stargate.forwardauth.trustForwardHeader=true

  warden:
    image: ghcr.io/soulteary/warden:latest
    container_name: warden
    restart: unless-stopped

    environment:
      - PORT=8081
      - MODE=ONLY_LOCAL
      - DATA_FILE=/app/data.json
      - REDIS_ENABLED=false
      - API_KEY=your-secret-api-key-here
      - RESPONSE_FIELDS=user_id,mail,phone,status,scope,role,name

    volumes:
      - ./data.json:/app/data.json:ro
      - /etc/localtime:/etc/localtime:ro

    networks:
      - auth-internal

    healthcheck:
      test: ["CMD-SHELL", "wget --quiet --tries=1 --spider http://localhost:8081/health || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 10s

networks:
  proxy:
    external: true

  auth-internal:
    internal: true
```

这只是一个示意配置，关键点有两个。

第一，Stargate 同时在 `proxy` 和 `auth-internal` 网络里。它需要通过 `proxy` 被 Traefik 访问，也需要通过 `auth-internal` 访问 Warden。

第二，Warden 只在 `auth-internal` 网络里。它不需要挂 Traefik label，也不需要暴露 `ports`，因为正常情况下，外部用户不应该直接访问 Warden。

真正会访问 Warden 的，是 Stargate 或其他可信内部调用方。

这和前面本地演示不一样。本地演示为了方便，我们用了：

```yaml
ports:
  - "8081:8081"
```

真实部署时，如果 Stargate 和 Warden 在同一个 Docker 网络里，就可以去掉端口暴露。这样访问路径会更清楚：

```Text
用户浏览器
    ↓
Traefik
    ↓
Stargate
    ↓
Warden
```

用户能看到 Stargate 的登录页面，但看不到 Warden。

### 用户状态怎么影响登录

接入 Warden 之后，`status` 就变得很重要了。

假设名单里有一个用户：

```json
{
  "mail": "admin@example.com",
  "phone": "13800138000",
  "user_id": "admin-001",
  "status": "active",
  "role": "admin",
  "scope": ["read", "write", "admin"],
  "name": "管理员"
}
```

当用户输入 `admin@example.com` 时，Stargate 会去问 Warden。如果 Warden 返回：

```json
{
  "user_id": "admin-001",
  "destination": {
    "email": "admin@example.com",
    "phone": "13800138000"
  },
  "status": "active",
  "channel_hint": "sms",
  "name": "管理员"
}
```

Stargate 就可以继续后面的登录流程。

如果你把这个用户改成：

```json
{
  "mail": "admin@example.com",
  "phone": "13800138000",
  "user_id": "admin-001",
  "status": "inactive",
  "role": "admin",
  "scope": ["read", "write", "admin"],
  "name": "管理员"
}
```

那他虽然还在名单里，但不应该继续登录。

这和直接删除用户不一样。直接删除时，系统只能知道：

```Text
查不到这个人
```

改成 `inactive` 时，系统能知道：

```Text
这个人存在，但现在不允许继续访问
```

对排查问题来说，后者会清楚很多。尤其是多人协作时，有人反馈“我为什么登录不了”，你可以直接从名单里看到他的状态，而不是反复猜他是不是输错了邮箱、手机号或密码。

### `role` 和 `scope` 怎么用

Warden 返回 `role` 和 `scope`，并不代表它要变成权限系统。它只是把基础身份信息提供给调用方。真正要不要使用这些字段，要看后面的系统怎么设计。

比如，Stargate 可以在认证成功后，把一部分用户信息写入请求头，再交给后端服务。后端服务可以看到：

```Text
X-Forwarded-User-Id: admin-001
X-Forwarded-Email: admin@example.com
X-Forwarded-Role: admin
```

如果你使用 Traefik ForwardAuth，还需要在 middleware 里显式配置允许转发哪些响应头。比如：

```yaml
- traefik.http.middlewares.stargate.forwardauth.authResponseHeaders=X-Forwarded-User,X-Forwarded-Email,X-Forwarded-User-Id,X-Forwarded-Role
```

这件事要谨慎。

请求头一旦进入后端服务，就会被后端当成可信身份信息。所以后端服务应该只接受来自反向代理的流量，不要让用户绕过 Traefik 直接访问后端。否则，用户就有机会自己伪造这些请求头。

这个问题和 Stargate 本身一样：

入口要统一。

后端不要裸露。

Warden 只负责提供身份信息，不能替你修复绕过入口的问题。

### 接入时最容易出错的地方

第一次把 Warden 接到 Stargate 后面，最容易出问题的地方通常不是代码，而是网络和配置。

比如，Stargate 访问不到 Warden。这时可以进到 Stargate 容器里测试：

```bash
wget -qO- http://warden:8081/health
```

如果这里都访问不了，先看 Docker 网络，不要急着看登录逻辑。

再比如，API Key 不一致。Warden 配的是：

```bash
API_KEY=abc
```

Stargate 配的是：

```bash
WARDEN_API_KEY=abcd
```

这种情况下，Warden 会拒绝查询。看起来像是“用户不存在”或者“登录失败”，但根因其实是服务间鉴权没通过。

还有一种常见问题，是用户状态不对。名单里有这个人，但状态是：

```json
"status": "inactive"
```

或者字段名写错了。比如写成了：

```json
"email": "admin@example.com"
```

但 Warden 期望的是：

```json
"mail": "admin@example.com"
```

这类问题最好先用 `/v1/lookup` 单独验证：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/v1/lookup?identifier=admin@example.com"
```

确认 Warden 自己能返回正确结果之后，再去看 Stargate。

基础设施排错时，我一般会把链路拆开看：

```Text
Warden 自己能不能查到用户？
    ↓
Stargate 能不能访问 Warden？
    ↓
Stargate 带的 API Key 对不对？
    ↓
用户 status 是不是 active？
    ↓
后续登录流程有没有继续？
```

不要一上来就从浏览器登录失败开始猜。链路越长，越要一段一段确认。

### 接入之后，Stargate 还是 Stargate

最后再强调一下边界。

接入 Warden 之后，Stargate 并没有变成用户系统，它只是多了一个准入判断来源。用户数据仍然在 Warden，登录流程仍然在 Stargate。后续如果再接 Herald，验证码发送和校验也应该交给 Herald。

这样拆开之后，后面替换起来会比较轻。你可以先用本地 `data.json` 跑 Warden，等名单变多了，再让 Warden 接远程 API。你可以先用 Stargate 的简单登录流程，等多人使用了，再加验证码。你也可以先不传 `role` 和 `scope` 给后端，等确实有服务需要这些字段，再通过请求头往下传。

不要第一天就把所有能力都打开。

先让 Stargate 能问 Warden。

先让 Warden 能稳定回答：

这个人还在不在名单里。

他现在还能不能继续往下走。

这一步跑通之后，再继续接 Herald。

## 真实使用时的几个建议

如果你准备把 Warden 放进自己的环境里，我建议不要一上来就把所有东西都接上。

基础设施类工具最怕的不是能力不够，而是第一步就铺得太大。一开始就接 Stargate、接 Herald、接远程数据源、接 Redis、配多实例、开监控，看起来很完整，但一旦出了问题，排查起来会很麻烦。

你很难判断问题到底出在哪里：是 Warden 没读到数据，是 API Key 不对，是 Stargate 访问不到 Warden，是用户状态不是 `active`，是 Herald 没把验证码发出去，还是反向代理和网络本身有问题。

所以我更建议小步接入。

先让名单自己跑起来，再让入口服务依赖这份名单，最后再把验证码、远程数据源、多实例和监控这些能力补上。

### 第一步，先用本地文件跑通

第一次使用 Warden，不要急着接远程 API，也不要急着接 Stargate。先准备一个最简单的 `data.json`，里面放一两个用户。

比如：

```json
[
  {
    "phone": "13800138000",
    "mail": "admin@example.com",
    "user_id": "admin-001",
    "status": "active",
    "scope": ["read", "write", "admin"],
    "role": "admin",
    "name": "管理员"
  }
]
```

然后用 `MODE=ONLY_LOCAL` 启动 Warden。

这一步只验证一件事：

Warden 能不能稳定地回答“这个人是不是在名单里”。

可以依次确认几个接口：

```bash
curl http://localhost:8081/health
```

确认服务启动正常。

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8081/
```

确认名单被加载。

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/user?mail=admin@example.com"
```

确认可以按邮箱查到用户。

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8081/v1/lookup?identifier=admin@example.com"
```

确认登录流程用的查询接口也能返回预期结果。

这一步跑通之前，不要急着接其他东西。因为 Warden 自己如果都还没稳定返回数据，后面接 Stargate 或 Herald，只会把问题藏得更深。

先把最短链路跑顺。

这比一次性把配置写完整更重要。

### 第二步，把 `status` 用起来

不要只把 Warden 当成邮箱和手机号列表。如果只是维护联系方式，那它很快会变成另一个通讯录。

Warden 更重要的价值，是让名单里的人有状态。

比如：

```json
{
  "mail": "user@example.com",
  "phone": "13900139000",
  "user_id": "user-001",
  "status": "active"
}
```

当这个人还应该继续访问内部服务时，状态是 `active`。如果他已经离开项目，或者暂时不应该继续登录，可以改成：

```json
{
  "mail": "user@example.com",
  "phone": "13900139000",
  "user_id": "user-001",
  "status": "inactive"
}
```

或者：

```json
{
  "mail": "user@example.com",
  "phone": "13900139000",
  "user_id": "user-001",
  "status": "suspended"
}
```

这样做比直接删除更容易排查问题。

直接删除时，系统只能知道：

```Text
查不到这个人。
```

保留用户并修改状态时，系统能知道：

```Text
这个人存在，但现在不允许继续访问。
```

这两个结果在管理上是不一样的。前者更像数据缺失，后者更像明确拒绝。

多人使用时，这个区别很有用。有人反馈“我为什么登录不了”，你可以直接看名单里的状态，而不是反复猜他是不是输错了邮箱、手机号，或者是不是某个配置没生效。

所以我建议从一开始就把 `status` 当成必填字段。

哪怕你的名单现在只有两个人，也最好写上。后面用户变多时，这个习惯会省很多事。

### 第三步，再接 Stargate 或其他调用方

等 Warden 自己跑稳之后，再让 Stargate、内部网关、脚本或平台来调用它。

这一步重点不是“登录页面好不好看”，而是确认服务之间的调用链路是不是可靠。

比如先确认 Stargate 能访问 Warden：

```bash
wget -qO- http://warden:8081/health
```

如果这里访问不了，先看 Docker 网络、服务名、端口和网络隔离，不要急着看登录逻辑。

然后确认 API Key 是否一致。

Warden 侧配置的是：

```bash
API_KEY=your-secret-api-key-here
```

Stargate 侧就应该是：

```bash
WARDEN_API_KEY=your-secret-api-key-here
```

这两个值不一致时，Stargate 查询 Warden 会失败。看起来可能像是“用户不存在”或者“登录失败”，但根因其实只是服务间鉴权没通过。

再确认用户状态。名单里有这个人，不代表他应该继续登录。如果返回的是：

```json
{
  "status": "inactive"
}
```

或者：

```json
{
  "status": "suspended"
}
```

那调用方就应该停下来。

最后再确认返回字段是否符合预期。比如 Stargate 需要 `user_id`、`mail`、`phone` 和 `status`，下游服务可能还需要 `role` 和 `scope`，那就检查 `RESPONSE_FIELDS` 有没有把这些字段放出来。

可以先用 `/v1/lookup` 单独验证：

```bash
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://warden:8081/v1/lookup?identifier=admin@example.com"
```

确认 Warden 返回正确之后，再去看 Stargate 的登录流程。

排查时尽量按顺序拆开：

```Text
Warden 自己能不能查到用户？
    ↓
调用方能不能访问 Warden？
    ↓
API Key 是否一致？
    ↓
用户状态是不是 active？
    ↓
返回字段是否够用？
    ↓
后续登录流程有没有继续？
```

不要一开始就从浏览器里的登录失败开始猜。

链路越长，越要一段一段确认。

### 第四步，再接 Herald

当你确认 Warden 已经能稳定回答“谁可以登录”之后，再接 Herald。

这时登录流程就可以从共享口令，逐步变成更适合多人使用的方式：

```Text
用户输入邮箱或手机号
    ↓
Stargate 调用 Warden 查询用户
    ↓
Warden 确认用户存在，并且状态是 active
    ↓
Stargate 调用 Herald 发送验证码
    ↓
用户输入验证码
    ↓
Stargate 创建会话
```

这里 Warden 仍然不发送验证码。它只返回用户状态和联系方式。

比如：

```json
{
  "user_id": "admin-001",
  "destination": {
    "email": "admin@example.com",
    "phone": "13800138000"
  },
  "status": "active",
  "channel_hint": "sms",
  "name": "管理员"
}
```

Herald 再根据这些信息决定怎么发送验证码：发短信，还是发邮件；验证码多久过期；失败几次要不要限制。这些都不应该塞进 Warden。

Warden 只管名单，Herald 只管送信，Stargate 只管登录流程和会话。

这样拆开之后，后面替换起来会轻很多。短信服务商换了，是 Herald 的事情；名单从本地文件换成远程 API，是 Warden 的事情；登录页、Cookie、ForwardAuth 和会话，是 Stargate 的事情。

不要让一个工具因为“顺手”就开始管太多。

一开始看起来省事，后面会很难拆。

### 第五步，再考虑远程数据源、Redis 和多实例

如果只是少量用户，本地文件已经很好用。尤其是 HomeLab、测试环境、小团队内部工具，或者几个临时服务，一个 `data.json` 加上 Git 记录，可能就够用了。

等名单开始变多，或者已经有其他系统在维护用户数据，再考虑远程数据源。

比如：

```bash
CONFIG=https://example.com/api/users.json
KEY=Bearer your-token-here
MODE=REMOTE_FIRST_ALLOW_REMOTE_FAILED
```

这时 Warden 可以从远程接口同步名单，也可以在远程异常时回退到本地数据。

但回退策略要谨慎。

它不是只有好处。如果远程系统里已经禁用了某个用户，而本地文件里还保留着旧的 `active` 状态，那么远程失败后回退到本地数据，就可能带来风险。

所以只要启用回退，就要想清楚几个问题：

- 本地数据是不是可信；
- 本地数据多久更新一次；
- 远程和本地冲突时，以谁为准；
- 远程失败时，是宁可拒绝登录，还是允许使用本地兜底。

这些不是配置问题，而是准入策略问题。

等 Warden 被多个系统依赖，或者需要多实例运行时，再考虑 Redis。

```bash
REDIS_ENABLED=true
REDIS=warden-redis:6379
```

Redis 可以帮助做缓存、分布式锁和多实例协调，但它不应该成为第一天的门槛。如果你只是想确认 Warden 能不能读一个 JSON 文件、查一个邮箱、返回一个状态，Redis 只会增加排查成本。

等最小链路稳定之后，再让系统变得更稳。

同样，OpenTelemetry、Prometheus、审计日志、健康检查访问限制，也都适合后面再加。这些能力很重要，但它们不应该挡在第一步前面。

我更建议的顺序是：

```Text
本地文件
    ↓
status 状态
    ↓
Stargate 或其他调用方
    ↓
Herald
    ↓
远程数据源
    ↓
Redis、多实例、监控和审计
```

这条路径不是最完整的，但它比较容易排错，也比较容易建立信心。

最后再提醒一句：Warden 不是完整 IAM。

它不管理组织架构，不负责复杂权限策略，不处理 OIDC、SAML，不提供完整管理后台，也不应该替代公司里已经成熟的 SSO 或身份中台。

如果你已经有这些系统，应该优先使用它们。

Warden 更适合站在中间地带：

你还没有必要引入完整身份系统，但已经不想继续靠共享口令、表格、聊天记录和散落在各个服务里的配置维护准入关系。

这时 Warden 可以先把名单收起来，让它变成一个可以被机器查询、可以被多个系统复用、可以逐步替换数据来源的小服务。

先别急着把它做大。

让它先把“谁还能进”这件事回答清楚。

## 上线前的最小安全检查

Warden 管的是准入名单，位置比普通内部小工具更敏感。

它本身不负责登录页面，也不签发会话，但会告诉调用方：这个人是谁、现在是不是 `active`、后续验证应该联系哪里，以及下游服务能不能拿到 `role` 和 `scope`。

所以 Warden 不应该裸奔，哪怕它只跑在内网里，也应该先把最基本的安全边界立起来。

### 查询接口必须有 API Key

第一件事，是确认 `API_KEY` 已经换成真实密钥，并且所有用户查询接口都必须带上它。不要让任何人都能直接查询用户名单。

至少下面这些接口，都应该被保护起来：

```Text
GET /
GET /data.json
GET /user
GET /v1/lookup
```

本地测试时，你可能会写：

```bash
API_KEY=your-secret-api-key-here
```

本地示例里的 `your-secret-api-key-here` 只适合演示，不要带进真实环境。真实环境里，不要继续用这种占位值，也不要用太短、太容易猜的字符串。

调用时带上：

```bash
curl -H "X-API-Key: your-real-api-key" \
  http://warden:8081/v1/lookup?identifier=admin@example.com
```

或者使用 Bearer 形式：

```bash
curl -H "Authorization: Bearer your-real-api-key" \
  http://warden:8081/v1/lookup?identifier=admin@example.com
```

这一步看起来很基础，但很重要。Warden 不是公开通讯录，更不是让外部用户随便探测“某个邮箱在不在名单里”的接口。

哪怕只是内部服务调用，也应该先有服务间鉴权。

### 不要把 Warden 直接暴露到公网

本地演示时，为了方便测试，我们用了：

```yaml
ports:
  - "8081:8081"
```

这样浏览器和 `curl` 都能直接访问 Warden。

但真实部署时，我不建议这样做。Warden 更适合只跑在内部网络里，由 Stargate、内部网关或其他可信调用方访问。

比如在 Docker Compose 里，让 Stargate 和 Warden 共享一个内部网络：

```yaml
networks:
  auth-internal:
    internal: true
```

然后 Warden 只加入这个网络：

```yaml
services:
  warden:
    image: ghcr.io/soulteary/warden:latest
    networks:
      - auth-internal
```

Stargate 也加入这个网络：

```yaml
services:
  stargate:
    image: soulteary/stargate:latest
    networks:
      - proxy
      - auth-internal
```

这样访问链路会更清楚：

```Text
用户浏览器
    ↓
Traefik / Nginx
    ↓
Stargate
    ↓
Warden
```

用户能访问的是入口服务，Warden 只给 Stargate 或其他可信内部调用方访问。

如果你的环境里确实需要跨机器访问 Warden，也尽量通过内网地址、VPN、专线、服务网格或受控反向代理来做。不要把它直接挂到公网域名下面。

如果不得不暴露，也至少要同时考虑：

```Text
TLS
API Key
IP 白名单
反向代理访问控制
速率限制
访问日志
```

不要只依赖“接口路径没人知道”。

这不是安全边界。

### 健康检查也不要随便暴露

Warden 的健康检查很方便：

```bash
curl http://localhost:8081/health
```

或者：

```bash
curl http://localhost:8081/healthcheck
```

它能告诉你服务是否正常、数据是否加载、Redis 是否启用、当前模式是什么。这对运维和排查问题很有用，但它也可能暴露一些你不想给外部知道的信息。

比如：

```json
{
  "status": "ok",
  "details": {
    "redis": "disabled",
    "data_loaded": true,
    "user_count": 2
  },
  "mode": "ONLY_LOCAL"
}
```

这里虽然没有直接泄露用户数据，但已经能看出服务状态、数据加载情况和运行模式。

所以生产环境里，不建议把健康检查直接暴露给公网。更合适的方式，是只允许本机、内网、反向代理或监控系统访问。

可以使用 Warden 的健康检查白名单：

```bash
HEALTH_CHECK_IP_WHITELIST=127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
```

也可以在 Nginx、Traefik、VPN 或内网安全组层面再做一层访问限制。

### 控制返回字段，别把所有信息都给出去

Warden 的用户对象可能会慢慢变多。

一开始只有：

```json
{
  "mail": "admin@example.com",
  "phone": "13800138000",
  "status": "active"
}
```

后面可能会加上：

```json
{
  "user_id": "admin-001",
  "role": "admin",
  "scope": ["read", "write", "admin"],
  "name": "管理员",
  "source": "manual",
  "note": "临时加入测试环境"
}
```

调试时，返回完整对象很方便。但真实环境里，不一定应该把所有字段都返回给所有调用方。

比如 Stargate 可能只需要：

```Text
user_id
mail
phone
status
scope
role
name
```

那就可以配置：

```bash
RESPONSE_FIELDS=user_id,mail,phone,status,scope,role,name
```

不要把 `note`、`source`、内部标记、同步来源、管理备注这类字段顺手给出去。

尤其是当 Warden 不只被 Stargate 调用，而是被多个内部系统复用时，更应该收紧返回字段。

字段暴露出去很容易，后面想收回来会麻烦很多。

### 远程数据源要可信

如果只用本地 `data.json`，风险主要在文件和部署环境。但如果开始接远程数据源，就要多想一步。

比如：

```bash
CONFIG=https://example.com/api/users.json
KEY=Bearer your-token-here
```

这里的远程接口会变成 Warden 的数据来源。也就是说，它会影响后续登录流程里“谁可以继续往下走”。

所以生产环境里，远程数据源至少应该满足几件事：

```Text
使用 HTTPS
接口需要认证
Token 不写进仓库
不跳过 TLS 校验
不指向不可信地址
远程返回的数据结构可控
```

不要从一个不受控的公开地址加载名单，也不要为了“先跑起来”就关闭 TLS 校验。

Warden 自己再怎么保护接口，如果数据源不可信，整条准入链路也会变得不可信。

另外，如果你用了远程失败回退模式，比如：

```bash
MODE=REMOTE_FIRST_ALLOW_REMOTE_FAILED
```

也要想清楚本地兜底数据是不是仍然可信。

远程系统里已经禁用的人，本地文件里是不是还保留着旧的 `active` 状态？如果远程挂了，回退到本地时，会不会把不该放行的人重新放进来？

这类问题不是 Warden 能替你自动决定的。它属于准入策略，你需要根据自己的环境做取舍。

对某些场景来说，远程失败时宁可拒绝登录；对另一些内部测试环境来说，本地兜底可能更实用。

关键是不要无意识地开启回退。

### 密钥不要进仓库

Warden 相关的密钥，最好都不要写进 Git 仓库。

包括：

```Text
API_KEY
KEY
REDIS_PASSWORD
HMAC 密钥
TLS 私钥
远程 API Token
```

本地测试写在 `compose.yaml` 里没什么问题。但只要进入真实环境，就应该换成更合适的方式。

比如：

```Text
环境变量
.env 文件
Docker Secret
Kubernetes Secret
部署平台的 Secret 管理
专门的密钥管理系统
```

如果使用 `.env`，至少确认它不会被提交：

```gitignore
.env
*.env
```

示例文件可以保留，比如：

```Text
.env.example
```

里面只放占位值：

```bash
API_KEY=change-me
KEY=Bearer change-me
REDIS_PASSWORD=change-me
```

不要为了方便，把真实 Token 写进示例配置。

这类东西一旦进了仓库，后面就不只是删掉那么简单。你还需要轮换密钥。

### 服务间通信可以逐步增强

第一阶段，用 API Key 就够简单。

Stargate 调用 Warden 时带上：

```bash
WARDEN_API_KEY=your-real-api-key
```

Warden 侧配置：

```bash
API_KEY=your-real-api-key
```

这能解决最基础的服务间鉴权问题。

但如果 Warden 已经变成认证链路里的关键组件，就可以继续往上加。

比如 HMAC。调用方不仅带一个静态 API Key，还对请求内容和时间戳做签名，这样可以降低请求被重放或伪造的风险。

再比如 mTLS。让 Stargate 和 Warden 之间通过客户端证书互相确认身份。

这类方案部署成本会高一些，不是第一天必须要做。但当 Warden 开始被多个服务依赖，或者运行在更复杂的网络环境里，就值得考虑。

我更建议的顺序是：

```Text
第一阶段：内部网络 + API Key
第二阶段：反向代理访问控制 + IP 白名单 + TLS
第三阶段：HMAC 或 mTLS
第四阶段：审计日志、指标和告警
```

不要第一天就把链路弄得太复杂，但也不要长期停留在“只要能访问到内网就能调用”的状态。

### 后端服务不要绕过入口

这一点更多和 Stargate 有关，但接入 Warden 后也一样重要。

如果后端服务可以绕过 Traefik、Nginx 或 Stargate 直接访问，那么前面的认证链路就不完整。

比如你让 Stargate 查询 Warden，Warden 返回用户身份，Stargate 再把用户信息写进请求头转给后端：

```Text
X-Forwarded-User-Id: admin-001
X-Forwarded-Email: admin@example.com
X-Forwarded-Role: admin
```

这时后端服务会把这些请求头当成可信身份信息。但前提是：这些请求只能来自反向代理或 Stargate。

如果用户可以直接访问后端服务，他就有机会自己伪造这些请求头。

所以后端服务应该只暴露在内部网络里，外部用户只能走统一入口。

这和 Stargate 的原则一样：

门装上了，后门也要关掉。

否则 Warden 再认真维护名单，入口链路也可能被绕开。

### 日志里不要留下太多敏感信息

Warden 排查问题时，日志很有用。但日志也很容易变成另一个数据泄露点。

尤其是用户查询接口，可能会带邮箱、手机号、`user_id`。如果日志里完整记录了请求参数、返回结果、Header 和 Token，就要小心了。

至少不要把这些东西原样打进日志：

```Text
API_KEY
Authorization
远程数据源 Token
完整手机号
完整邮箱
验证码相关字段
内部备注字段
```

调试环境可以稍微放开一点，生产环境里最好做脱敏。比如手机号只保留后四位，邮箱只保留部分字符，Token 只显示前后几位，或者完全不显示。

日志是为了排查问题。

不是为了复制一份用户数据。

### 一个最小但比较稳的部署形态

如果只是内部使用，我觉得比较稳的起步方式大概是这样：

```Text
Warden 只在内部网络里
    ↓
查询接口必须带 API Key
    ↓
健康检查只给监控或内网访问
    ↓
返回字段用 RESPONSE_FIELDS 收紧
    ↓
密钥通过环境变量或 Secret 注入
    ↓
后端服务不能绕过 Stargate
```

对应到 Compose，大概像这样：

```yaml
services:
  warden:
    image: ghcr.io/soulteary/warden:latest
    container_name: warden
    restart: unless-stopped

    environment:
      - PORT=8081
      - MODE=ONLY_LOCAL
      - DATA_FILE=/app/data.json
      - REDIS_ENABLED=false
      - API_KEY=${WARDEN_API_KEY}
      - RESPONSE_FIELDS=user_id,mail,phone,status,scope,role,name
      - HEALTH_CHECK_IP_WHITELIST=127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

    volumes:
      - ./data.json:/app/data.json:ro
      - /etc/localtime:/etc/localtime:ro

    networks:
      - auth-internal

    healthcheck:
      test: ["CMD-SHELL", "wget --quiet --tries=1 --spider http://localhost:8081/health || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 10s

networks:
  auth-internal:
    internal: true
```

这里没有 `ports`。这意味着 Warden 不会直接暴露到宿主机端口。

同一个内部网络里的 Stargate 可以访问它，外部用户不应该直接访问它。

如果你需要本地调试，可以临时加上：

```yaml
ports:
  - "8081:8081"
```

调试完成后再去掉。**不要把调试配置直接带进生产环境。** 上线前，可以简单过一遍：

```Text
API_KEY 是否已经设置？
示例密钥是否已经替换？
Warden 是否只在内部网络里？
是否去掉了不必要的 ports？
健康检查是否限制访问范围？
RESPONSE_FIELDS 是否收紧？
远程数据源是否使用 HTTPS？
远程 API Token 是否通过 Secret 注入？
Redis 密码是否没有写进仓库？
后端服务是否只能从统一入口访问？
日志里是否避免记录 Token 和完整用户信息？
```

这不是为了把 Warden 做成一个很重的系统，而是因为它在认证链路里位置比较敏感。它管的不是普通配置，它管的是：

- 谁还能进。
- 谁不该进。
- 后续验证应该发给谁。

这几件事值得稍微认真一点。

## 最后

很多内部服务的认证问题，并不是一开始就很复杂。

最开始只是一个密码、一个测试面板、一个临时后台、一个内部文档站。几个人知道地址，几个人知道口令，这样先跑起来，没什么问题。

真正的问题通常是后来出现的。

服务慢慢变多，使用的人慢慢变多，入口也慢慢变多。这时候，原来那把共享钥匙就开始不够用了。

你会开始关心更多问题：

- 这个人是谁；
- 他现在还在不在项目里；
- 他是不是还应该继续登录；
- 验证码应该发到哪里；
- 下游服务能不能拿到他的 `user_id`；
- 有没有必要区分 `role` 和 `scope`。

如果这些问题全部塞进认证入口里，Stargate 会越来越重。

如果每个服务都自己维护一份名单，用户数据又会散得到处都是。

如果直接上完整 IAM，对很多 HomeLab、小团队内部工具、测试环境和临时服务来说，又可能太早、太重。

所以这里还是那个中间地带。

我们不是不知道完整身份系统更强，只是很多时候，眼前的问题没到那一步。我们需要的可能只是：先把裸奔的服务挡住，再把共享口令换成名单，然后让验证码、会话、用户状态、下游身份信息这些东西，一步一步接上来。

Stargate 解决的是第一步：先把门装上。

Warden 解决的是第二步：让这道门不要只认一把共享钥匙，而是开始认人。

Herald 后面要解决的是第三步：把验证码和消息送到该送的人手里。

这三个工具放在一起，并不是想重新做一套完整 IAM，它们也不应该假装自己是完整 IAM。完整 IAM 要解决的是组织、账号、协议、权限、审计、生命周期和一整套治理问题。

而 Stargate、Warden、Herald 更像是几个可以独立工作的基础设施小工具。

每个工具只先解决一个具体问题：

- Stargate 负责守入口；
- Warden 负责管名单；
- Herald 负责送验证码。

这几件事拆开之后，Stargate 不需要变成用户数据库，Warden 也不需要理解登录页和验证码流程，Herald 也不用关心谁有资格登录。

它们可以单独使用，也可以组合起来。

你可以先只用 Stargate，用共享口令把几个内部服务保护起来。等共享口令不够用了，再接 Warden，用邮箱、手机号或 `user_id` 判断谁还能继续登录。等登录流程需要更明确的验证，再接 Herald，把验证码发出去。

再往后，如果服务更多、要求更高，再考虑 Redis、多实例、审计日志、监控指标、HMAC、mTLS，或者直接接入更完整的身份体系。

这条路径的重点不是“功能最多”，而是每一步都能解释清楚为什么要加。

第一天不要太重，但也不要一直停在共享口令里。

Warden 想补的，就是共享口令之后、完整 IAM 之前的那一段。

它让“谁可以进”这件事，从聊天记录、表格、脚本、环境变量和各个服务自己的配置里收回来，变成一份可以被机器稳定查询的准入名册。

这份名单一开始可以只是一个 `data.json`，但它至少让系统开始知道：谁是这个人、他现在是什么状态、后续验证应该联系哪里，以及需要的话，下游服务能拿到哪些基础身份信息。

这不是什么宏大的系统。

但对很多内部工具、测试服务、小团队平台和 HomeLab 场景来说，已经能把一件长期别扭的事情理顺很多。

先装门，再认人，最后送信。

如果这个项目对你有帮助，欢迎到 GitHub 顺手点个 Star：[https://github.com/soulteary/warden](https://github.com/soulteary/warden)

> 星门启闭，守望验身，鸦使送信。

下一篇，我们继续聊“鸦使”：Herald。

--EOF