https://grpc-kit.com/docs/guides/admin/Recent content in Admin 后台 on gRPC KitHugozh-cnSat, 26 Sep 2026 22:35:59 +0800https://grpc-kit.com/docs/guides/admin/enable/Sat, 26 Sep 2026 00:00:00 +0800https://grpc-kit.com/docs/guides/admin/enable/<h2 id="简要概述">简要概述</h2> <p>内置 admin 管理后台由三部分组成，配置缺一不可：</p> <table> <thead> <tr> <th>组成</th> <th>路由</th> <th>由哪个配置项开启</th> </tr> </thead> <tbody> <tr> <td>KnownAdmin gRPC 服务 + HTTP API</td> <td><code>/builtin/admin/api/v1/...</code></td> <td><code>services.integrations.grpc.admin</code></td> </tr> <tr> <td>前端静态资源托管</td> <td><code>/admin</code></td> <td><code>frontend.interface.admin</code></td> </tr> <tr> <td>业务数据库（lion）</td> <td>—</td> <td><code>database</code></td> </tr> </tbody> </table> <h2 id="必须配置项">必须配置项</h2> <table> <thead> <tr> <th>配置项</th> <th>作用</th> <th>缺失后果</th> </tr> </thead> <tbody> <tr> <td><code>services.integrations.grpc.admin: true</code></td> <td>注册 KnownAdmin gRPC 服务与 <code>/builtin/admin/api/v1</code> HTTP 路由</td> <td>无 admin API，前端登录接口 404</td> </tr> <tr> <td><code>services.http_address</code></td> <td>HTTP gateway 监听地址</td> <td>gateway 不开启，admin API 与前端均无入口</td> </tr> <tr> <td><code>services.security_key</code></td> <td>admin 模块 AES 密钥（16/24/32 字节）</td> <td>DB 中 email、凭证、JWKS 私钥等加密字段无法加解密</td> </tr> <tr> <td><code>database.enable</code> + 连接信息</td> <td>admin 业务数据（用户/角色/凭证等）</td> <td>admin 服务降级：仅静态用户可登录，无用户管理等后台功能</td> </tr> <tr> <td><code>frontend.enable: true</code></td> <td>前端托管总开关</td> <td><code>/admin</code> 页面不可访问</td> </tr> <tr> <td><code>frontend.interface.admin.enabled: true</code></td> <td>admin 前端托管开关（默认 <code>false</code>）</td> <td>同上</td> </tr> <tr> <td><code>security.authentication.oidc_provider</code></td> <td><strong>登录必需</strong>（见下文）</td> <td>登录一律 400 <code>access token client_id is required</code></td> </tr> <tr> <td><code>security.authentication.http_users</code></td> <td>本地静态用户（可选，DB 用户亦可登录）</td> <td>只能使用 DB 用户登录</td> </tr> <tr> <td><code>security.authorization.allowed_roles</code> + 用户的 <code>roles</code></td> <td>admin API 访问授权</td> <td>登录成功后所有 admin API 返回 403</td> </tr> </tbody> </table> <p><code>frontend.interface.admin.embedded: true</code> 使用二进制内嵌的前端资源（推荐本地使用）， <code>handle_url</code> 控制挂载路径（默认 <code>/admin</code>）。</p>