> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arupa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理 API

> 了解 Arupa 如何通过 HTTP 暴露管理能力，以及如何逐一开关这些能力。

Arupa 可以通过 HTTP 管理自身的大部分配置：用户、组、页面、主机访问规则、服务、日志记录以及网络设置。这些默认都不可用。每个领域都是一个独立的**能力（capability）**，在某个能力被显式启用之前，它对应的接口对调用者来说并不存在。

## `[API]` 表

能力由 `config.toml` 中的 `[API]` 表控制：

```toml theme={null}
[API]
User    = true
Group   = true
Pages   = false
Access  = false
Service = true
Log     = false
Network = false
```

每个字段都是一个布尔值，对应一个能力，未设置时默认都是 `false`。一个刚安装好的 Arupa 不会暴露这些接口中的任何一个——只有会话相关的接口（`/api/login`、`/api/logout`、`/api/check-auth`）以及两个内核信息接口（`GET /api/kernel/version`、`POST /api/kernel/reload`）可以开箱即用，因为它们不受能力开关控制。

| 能力      | `[API]` 字段 | 覆盖范围                   |
| ------- | ---------- | ---------------------- |
| User    | `User`     | [用户账户](./api-user)     |
| Group   | `Group`    | [组](./api-group)       |
| Pages   | `Pages`    | [错误页面](./api-pages)    |
| Access  | `Access`   | [主机访问规则](./api-access) |
| Service | `Service`  | [服务管理](./api-service)  |
| Log     | `Log`      | [日志记录](./api-log)      |
| Network | `Network`  | [网络设置](./api-network)  |

## 启用一个能力

没有任何 HTTP 接口可以用来开关某个能力——如果有，一个已通过身份验证的调用者就能解锁比管理员本意更多的 API。启用一个能力意味着直接编辑 `config.toml` 中的 `[API]` 表，方式与编辑配置的其他任何部分完全相同。

修改会在下一次配置重新加载时生效。向内核进程发送 `SIGHUP`，或者调用 `POST /api/kernel/reload`，都可以在不完全重启的情况下让它生效——这是两个永远不受能力开关限制的接口之一，因此即使所有其他能力都被禁用，它也始终可用。

## 开关机制如何工作

本章节各页面描述的每一个接口都要求请求已通过身份验证，与其他管理接口完全一样。在此之上，内核会在处理程序运行之前检查该接口所属的能力是否已启用：

* 如果该能力被禁用，请求永远不会到达处理程序，内核会返回 `404 Not Found`；
* 如果该能力已启用，请求会正常进入身份验证和处理逻辑。

一个被禁用的能力，其响应与一个根本不存在的路径完全相同。这是刻意设计的：它避免向未经身份验证或权限不足的调用者透露某个管理入口只是被关闭了、而不是根本不存在。身份验证仍然会最先被检查，因此一个没有有效会话的请求会收到正常的 `401 Unauthorized`，无论目标能力是否启用。

能力开关与 `Route.Allow` 或任何其他访问策略是相互独立的。某个能力被启用只意味着它的接口存在；某个已通过身份验证的用户是否可以调用这些接口，仍然由[访问控制](./config-access)决定。

## 响应结构

本章节的每个接口都返回 Arupa 管理 API 通用的信封结构：

```json theme={null}
{
  "success": true,
  "message": "...",
  "data": { ... }
}
```

失败的请求使用相同的 `success`/`message` 字段，`success` 为 `false`，并带有相应的 HTTP 状态码，不包含 `data`。

## requires\_restart 字段

有些接口会在响应中报告一个 `requires_restart` 布尔字段。凡是只在内核启动时读取一次的设置——监听地址、TLS、服务临时目录、日志级别/格式——都是这样工作的。这个值告诉您刚写入的值是否与正在运行的进程实际生效的值不同，而不是告诉您写入操作本身是否成功。下面每个页面都会说明各自哪些字段属于这种情况。