更新 API 接口说明

Author: Andyguo5891

docs/dev_manual/api_manual.md

@@ -1,87 +1,95 @@
-## API 接口配置与使用指南
 
+!!! note ""
 本文档详细介绍了如何在三方服务中使用自定义 Token 的验证来访问面板接口。
 
-### 以下内容已通过 Swagger 进行验证
+## 1 接口配置说明
 
-面板 swagger 访问地址：`{host}:{port}/1panel/swagger/index.html`
+!!! note ""
+    
+    登录后，可通过访问 swagger 访问地址：`{host}:{port}/1panel/swagger/index.html` 查看所有 API。
 
-### 自定义 Token 格式
+### 1.1 自定义 Token 格式
 
-我们设计了以下自定义 Token 格式，用于接口请求的身份验证：
+!!! note ""
 
-```text
-Token = md5('1panel' + API-Key + UnixTimestamp)
-```
+    1Panel 设计了以下自定义 Token 格式，用于接口请求的身份验证：
 
-组成部分：
+    ```text
+    Token = md5('1panel' + API-Key + UnixTimestamp)
+    ```
 
-- 固定前缀: '1panel'
-- API-Key: 面板 API 接口密钥
-- UnixTimestamp: 当前的时间戳（秒级）
+    组成部分：
 
-### 请求 Header 设计
+    - 固定前缀: '1panel'
+    - API-Key: 面板 API 接口密钥
+    - UnixTimestamp: 当前的时间戳（秒级）
 
-每次请求必须携带以下两个 Header：
+### 1.2  请求 Header 设计
 
-| Header 名称        | 说明              |
-|------------------|--------------------|
-| 1Panel-Token     | 自定义的 Token 值    |
-| 1Panel-Timestamp | 当前时间戳           |
+!!! note ""
 
-### 示例请求头：
+    每次请求必须携带以下两个 Header：
+    
+    | Header 名称        | 说明              |
+    |------------------|--------------------|
+    | 1Panel-Token     | 自定义的 Token 值    |
+    | 1Panel-Timestamp | 当前时间戳           |
 
-```bash
-curl -X GET "http://localhost:4004/api/v1/dashboard/current" \
--H "1Panel-Token: <1panel_token>" \
--H "1Panel-Timestamp: <current_unix_timestamp>"
-```
+    示例请求头：
+    
+    ```bash
+    curl -X GET "http://localhost:4004/api/v1/dashboard/current" \
+    -H "1Panel-Token: <1panel_token>" \
+    -H "1Panel-Timestamp: <current_unix_timestamp>"
+    ```
 
-### 示例实现代码(go)
+### 1.3 示例实现代码
 
-```go
-func validateToken(c *gin.Context) error {
-    panelToken := c.GetHeader("1Panel-Token")
-    panelTimestamp := c.GetHeader("1Panel-Timestamp")
-    systemToken := panelToken
-    systemKey = ******* // 面板 API 密钥
-    expectedToken := md5Sum("1panel" + systemKey + panelTimestamp)
-    if systemToken != expectedToken {
-        return fmt.Errorf("invalid token")
-    }
-    return nil
-}
+!!! note ""
+    以 go 语言为例，展示对应的实现代码：
 
-func md5Sum(data string) string {
-    h := md5.New()
-    h.Write([]byte(data))
-    return hex.EncodeToString(h.Sum(nil))
-}
-```
+    ```go
+    func validateToken(c *gin.Context) error {
+        panelToken := c.GetHeader("1Panel-Token")
+        panelTimestamp := c.GetHeader("1Panel-Timestamp")
+        systemToken := panelToken
+        systemKey = ******* // 面板 API 密钥
+        expectedToken := md5Sum("1panel" + systemKey + panelTimestamp)
+        if systemToken != expectedToken {
+            return fmt.Errorf("invalid token")
+        }
+        return nil
+    }
+    
+    func md5Sum(data string) string {
+        h := md5.New()
+        h.Write([]byte(data))
+        return hex.EncodeToString(h.Sum(nil))
+    }
+    ```
 
-## 注意事项
+## 2 注意事项
 
-1. 时间戳的有效性:
-需要确保服务器与客户端时间同步，否则会导致验证失败。建议使用 NTP 同步时间。
+!!! note ""
 
-2. 白名单使用:
-将可信任的 IP 或 IP 段加入白名单，避免频繁 Token 验证的开销；如需放行所有 IP ，可以配置 `0.0.0.0`。
+    - 时间戳的有效性:需要确保服务器与客户端时间同步，否则会导致验证失败。建议使用 NTP 同步时间。
+    - 白名单使用:将可信任的 IP 或 IP 段加入白名单，避免频繁 Token 验证的开销；如需放行所有 IP ，可以配置 `0.0.0.0`。
 
-## 常见问题
+## 3 常见问题
 
-1. Q: 如果 1Panel-Token或1Panel-Timestamp 错误怎么办？
-   A: 返回 401 Unauthorized，提示 "API 接口密钥错误"。
+!!! note ""
+    
+    （1）如果 1Panel-Token或1Panel-Timestamp 错误怎么办？
+    后台将返回 401 Unauthorized，并提示 "API 接口密钥错误"。
 
-2. Q: 如何生成 1Panel-Token？
-   A: 参考以下伪代码：
+    （2）如何生成 1Panel-Token？
 
-```javascript
-const token = md5('1panel' + clientToken + unixTimestamp);
-```
+    请参考以下伪代码：
 
-3. Q: 为什么需要两个 Header？
-   A: 提高验证的复杂度，同时增强安全性。
+    ```javascript
+    const token = md5('1panel' + clientToken + unixTimestamp);
+    ```
 
-## 结语
+    （3）为什么需要两个 Header？
+    提高验证的复杂度，同时增强安全性。
 
-通过上述方式可以实现一个安全、高效的 Token 验证系统。如果有任何问题，请参考具体代码实现或联系我们获取支持。