# 登录方式与 Portainer 配置

不设置 `BI_AUTH_MODE` 时默认 `sso`，沿用业务系统 jumpToken 登录。
设置 `BI_AUTH_MODE=password` 时只开放固定密码登录，关闭 SSO 换票入口。
浏览器从 `/api/auth/config` 获取模式，密码不会打包到前端，不使用 VITE_ 密码变量。

## Portainer Stack

在现有 BI 服务的 `environment` 中合并以下配置，保留原镜像、端口、数据库等配置：

```yaml
environment:
  BI_AUTH_MODE: ${BI_AUTH_MODE:-sso}
  BI_AUTH_PASSWORD: ${BI_AUTH_PASSWORD:-}
  JWT_SECRET: ${JWT_SECRET:?必须配置独立的随机签名密钥}
  DEV_BYPASS_AUTH: "0"
  NODE_ENV: production
```

在 Stack 的 Environment variables 区域录入以下名称和值：

| 名称 | 固定密码模式 | SSO 模式 |
| --- | --- | --- |
| BI_AUTH_MODE | password | sso |
| BI_AUTH_PASSWORD | 独立随机密码，至少 16 字符 | 留空 |
| JWT_SECRET | 独立随机密钥，至少 32 字符 | 保留部署专用密钥 |

不要把真实密码提交进 Git。Portainer 中填写的 Stack 变量必须通过上面的 environment 映射才能进入容器。
更新 Stack 并重新创建容器；单纯 Restart 不会更新容器环境变量。
容器方式部署：Duplicate/Edit → Advanced container settings → Env，填写同样变量，再重新部署。
需要先构建包含本功能的新镜像；旧镜像不认识这些变量。

## 权限、安全和验证

- 固定密码身份是共享只读身份，具有全量看板数据读取范围及能源访问权限，无调度/反馈管理角色；服务端拒绝写入方法。
- 会话有效期 8 小时。更换密码、JWT_SECRET 或切换模式后，原密码会话失效。
- 每个服务实例 15 分钟最多 20 次密码验证请求；多副本需在网关配置共享限流。共享限流可能被恶意请求耗尽，建议只在内网或受控网络开放。
- 外网必须使用 HTTPS，避免明文传输密码和令牌。密码/环境变量对拥有容器管理权限的人可见。
- 密码少于 16 字符或签名密钥少于 32 字符时拒绝登录；无默认访问密码。不要沿用镜像中的旧默认 JWT_SECRET。
- DB_READ_ONLY=1 时密码登录仍可用，业务写入仍被禁止。
- 测试未登录访问、错误密码、正确密码、刷新恢复会话；切回 sso 后检查跳转登录。
- 开发免登录仅 SSO 开发模式生效，生产必须保持 DEV_BYPASS_AUTH=0。

Portainer 官方说明：https://docs.portainer.io/user/docker/containers/advanced
以及 https://docs.portainer.io/sts/user/docker/stacks/add