</details>

<details>
<summary><strong>自定义 SSH 密钥对</strong></summary>

默认情况下，Bastillion 在首次启动时会生成自己的 Ed25519 密钥对。若要使用您自己的密钥，
最简单的方式是通过界面操作：**设置 → 替换应用程序 SSH 密钥**
（仅限管理员账户）——粘贴私钥、公钥以及口令（如果有的话），
更改会立即生效，无需重启。

⚠️ 这会替换所有已注册系统所信任的*那一把*密钥。此操作旨在作为首次设置 Bastillion 时的一次性步骤，
**在**您注册任何系统**之前**执行——如果您已经注册了系统，那么替换密钥的瞬间 Bastillion 就会失去对所有系统的 SSH 访问权限，
除非这把确切的密钥已经预先存在于每台系统的 `authorized_keys` 中。
设置页面在您已注册系统的情况下会要求额外的确认复选框，正是出于这个原因。

**已经注册了系统但仍需要轮换密钥？** 请通过 Bastillion 本身预先部署新密钥，
而不是手动在各处编辑 `authorized_keys`：

1. 将 `FORCE_USER_KEY_GENERATION=false` 设置好，这样 **管理 SSH 密钥 → 添加 SSH 密钥** 就允许您粘贴
   现有的公钥，而不仅仅是生成新密钥。
2. 在那里针对覆盖所有系统的配置文件添加新密钥，并确认（在管理 SSH 密钥下，
   或每台系统的状态中）它确实已部署到所有位置——请留意
   `AUTH_KEYS_REFRESH_INTERVAL`，因为正是它负责推送该密钥。
3. 只有在确认新密钥已到达每台系统后，才在设置中替换应用程序密钥。
4. 将 `FORCE_USER_KEY_GENERATION` 恢复为先前的值，然后在确认新应用程序密钥已传播到所有系统后
   （再次留意 `AUTH_KEYS_REFRESH_INTERVAL`），从管理 SSH 密钥中移除您在步骤 2 中添加的密钥——
   它只是临时部署在那里以预置 `authorized_keys`，后续不再需要。

对于脚本化/无头环境，也可以通过环境变量并重启来完成同样的操作：```bash
# Regenerate and import SSH keys
export RESET_APPLICATION_SSH_KEY=true

# Private key
export PRIVATE_KEY=/Users/you/.ssh/id_rsa

# Public key
export PUBLIC_KEY=/Users/you/.ssh/id_rsa.pub

# Passphrase (leave blank if none)
export DEFAULT_SSH_PASSPHRASE=myPa$$w0rd

</details>

<details>
<summary><strong>数据库设置</strong></summary>

嵌入式 H2 示例：```bash
export DB_USER=bastillion
export DB_PASSWORD=p@$$w0rd!!
export DB_DRIVER=org.h2.Driver
export DB_CONNECTION_URL=jdbc:h2:file:keydb/bastillion;CIPHER=AES;

</details>

<details>
<summary><strong>外部认证（LDAP / JAAS）</strong></summary>

改为（或同时）针对现有的 LDAP/Active Directory 服务器进行认证，而不是使用本地密码。启用方式：```bash
export JAAS_MODULE=ldap-ol

要将LDAP角色映射到Bastillion配置文件：```
ldap-ol-with-roles {
    org.eclipse.jetty.security.jaas.spi.LdapLoginModule required
    debug="false"
    useLdaps="false"
    contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
    hostname="<SERVER>"
    port="389"
    bindDn="<BIND-DN>"
    bindPassword="<BIND-DN PASSWORD>"
    authenticationMethod="simple"
    forceBindingLogin="true"
    userBaseDn="ou=users,dc=bastillion,dc=com"
    userRdnAttribute="uid"
    userIdAttribute="uid"
    userPasswordAttribute="userPassword"
    userObjectClass="inetOrgPerson"
    roleBaseDn="ou=groups,dc=bastillion,dc=com"
    roleNameAttribute="cn"
    roleMemberAttribute="member"
    roleObjectClass="groupOfNames";
};

</details>

<details>
<summary><strong>单点登录（SAML 2.0）</strong></summary>

针对企业身份提供程序进行身份验证——Microsoft Entra ID、Okta、ADFS 或任何
SAML 2.0 IdP——而不是（或同时使用）本地密码或 LDAP。配置完成后，登录页面会出现一个 **使用 SSO 登录**
按钮。启用它：```bash
export SAML_BASE_URL=https://bastillion.example.com
export SAML_IDP_METADATA_URL=https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml?appid=<app-id>

仅当 IdP 侧注册的实体 ID 无法与 `SAML_BASE_URL` 完全匹配时才需要：```bash
export SAML_SP_ENTITY_ID=https://bastillion.example.com

管理员在首次 SSO 登录时被添加，并可被分配系统配置文件。

**Bastillion 中显示的用户名：** SAML NameID 成为用户名。Entra 默认发送
`user.userprincipalname`，这对普通租户成员来说没问题，但对于 B2B 访客（任何使用个人或外部电子邮件作为访客添加并登录的人），会产生一个难看的访客 UPN，例如 `alice_gmail.com#EXT#@yourtenant.onmicrosoft.com`。为了获得更简洁的用户名，请前往企业应用程序的 *单一登录* → SAML → *属性与声明*，编辑 **唯一用户标识符（Name ID）**，并将其 *源属性* 从 `user.userprincipalname` 更改为 `user.mail`。

**角色映射的实际工作原理——与上述 LDAP 机制相同：** `SAML_ROLE_ATTRIBUTE` 指定 *哪个* 断言属性携带用户的组/角色；该属性在特定登录时持有的 *值* 会与您在 **管理 → 配置文件** 下创建的配置文件名称进行 **精确文本匹配** 比较。与配置文件名称匹配的值会将用户分配到该配置文件；声明的其他任何内容都无关紧要。因此，Bastillion 配置文件必须与断言发送的字符串完全同名——没有单独的映射步骤或 UI，名称只需对齐即可。

这正是人们在使用 Entra ID 时最容易出错的部分：默认情况下，Entra 的组声明可以将每个组作为其 **对象 ID**（一个 GUID）发出，而不是其显示名称，除非企业应用程序的令牌配置被明确设置为发出组 **名称**。如果您的 Bastillion 配置文件命名为 `admins`/`everyone` 之类，但 Entra 发送的是 GUID，则永远不会匹配。在假设映射损坏之前，请检查实际断言中的声明值（或该应用的 Entra 令牌配置）——通常问题出在这里，而不是 Bastillion 端。有三种修复方法，按我们推荐的顺序排列：

1. **使用 Entra 应用角色而不是组声明（最干净）。** 在应用的注册 → 应用角色下，定义具有您想要的确切值的角色（`admins`、`everyone`、...），然后在企业应用程序的 *用户和组* 下将用户/组分配到这些角色。配置 SAML 令牌以发出 `roles` 声明，并将 `SAML_ROLE_ATTRIBUTE` 指向该声明的 URI，而不是组声明。您可以选择 Entra 发送的确切字符串——完全没有 GUID 问题，而且这比重新利用 AD 组是更清晰的授权模型。
2. **更改组声明的源属性。** 企业应用程序 → 单一登录 → SAML → *属性与声明* → 编辑组声明 → 有一个 *源属性* 下拉菜单，通常默认为组 ID。根据您的租户以及组是仅云还是从本地 AD 同步，您可能可以将其切换为 `sAMAccountName` 或显示名称选项——确切选项因租户和 Entra 门户版本而异，因此请检查实际提供的选项，而不是假设特定标签。
3. **或者不要与之对抗——将 Bastillion 配置文件命名为 Entra 实际发送的任何内容。** 如果 Entra 坚持发送 GUID，则创建一个字面命名为该 GUID 的 Bastillion 配置文件。虽然更难看，但无需任何 Entra 端重新配置。

声明与任何 Bastillion 配置文件都不匹配的用户将在登录时被拒绝（**Manager** 账户是唯一例外；它们不受配置文件范围限制）——与 LDAP 完全相同，因此出于与设置 `DEFAULT_PROFILE_FOR_LDAP` 相同的原因，值得设置上述 `DEFAULT_PROFILE_FOR_SAML`：在您仍将配置文件名称与 IdP 的声明值对齐时，它是一个安全网。

Bastillion 自身的一次性密码检查对 SSO 登录跳过——IdP 应强制执行其自身的 MFA/条件访问策略。首次 OTP 注册仍然提供，以便 SAML 用户在 SSO 被禁用时拥有可用的本地备用凭据。

**签名请求和加密断言：** Bastillion 在首次需要时自动生成自己的 SAML 签名证书（自签名，与其生成 TLS 证书的方式相同），并从此用它签署每个出站 AuthnRequest——无需设置，即使您的 IdP 不检查它也无害。获取 `https://bastillion.example.com/saml/metadata` 以标准 SP 元数据形式获取该证书，如果您的 IdP 管理员应验证 Bastillion 的签名请求或应为 Bastillion 加密断言，请将其交给他们——大多数 IdP 可以直接导入 SP 元数据 URL，而不是粘贴原始证书。如果您希望使用真实的（例如 CA 颁发的）密钥对而不是自动生成的密钥对，请将 `SAML_SP_KEYSTORE_PATH`/`SAML_SP_KEYSTORE_PASSWORD` 指向包含该密钥对的 PKCS12 密钥库。要 *要求* 加密断言（默认关闭——仅在您的 IdP 实际配置为使用 Bastillion 的证书加密后才启用此选项，否则每次登录都会开始失败）：```bash
export SAML_WANT_ENCRYPTED_ASSERTIONS=true

还有一个基于文件的审计日志，默认处于禁用状态。在 **log4j2.xml** 中取消注释以下内容即可启用：
- `io.bastillion.manage.util.SystemAudit`
- `audit-appender`

> https://github.com/bastillion-io/Bastillion/blob/main/src/main/resources/log4j2.xml#L19-L22
</details>

<details>
<summary><strong>从 v4 迁移</strong></summary>

从旧版 Bastillion v4 安装升级，并希望保留你的用户、系统、配置文件、脚本，以及（最重要的是）应用现有的 SSH 密钥对，而不是从头开始？`tools/migrate/` 提供了一个独立的迁移工具，正是为此而设计——它将旧 H2 数据库中的每个表导出（使用旧实例的密钥库解密应用级加密列）到 JSON 文件，然后将其导入全新的 v5 实例（使用新实例的密钥库重新加密）。现有用户迁移后即可立即使用当前密码登录——无需强制重置。```bash
cd tools/migrate

# 1. Export the old database
./migrate.sh export /opt/Bastillion-jetty/jetty/bastillion/WEB-INF/classes/ ~/bastillion-export.json

# 2. Start the new v5 instance once against the config dir you're migrating into, then
#    stop it (Ctrl+C) once it's finished booting - this creates the schema, jceks, and
#    default admin user.
cd ../..
java -DCONFIG_DIR=/data/bastillion/ -jar target/bastillion-5.0.0-SNAPSHOT.jar

# 3. Import into the new database (full replace of all 12 tables)
cd tools/migrate
./migrate.sh import /data/bastillion/ ~/bastillion-export.json --yes-replace-all-data

# 4. Delete the export file - it contains decrypted secrets
rm ~/bastillion-export.json