此翻译是使用机器学习生成的，可能不是100%准确。 查看英文版本

I2PControl JSON-RPC

通过 I2PControl webapp 进行远程 router 管理的 API

Updated: 2025-10 Accurate for: 2.10.0

————-检查添加内容————–

I2PControl API 文档

I2PControl 是一个与 I2P router 捆绑的 JSON-RPC 2.0 API（自 0.9.39 版本起）。它通过结构化的 JSON 请求实现对 router 的认证监控和控制。

默认密码： itoopie — 这是出厂默认密码，出于安全考虑应当立即更改。

1. 概览与访问

ImplementationDefault EndpointProtocolEnabled by DefaultNotes
Java I2P (2.10.0+)http://127.0.0.1:7657/jsonrpc/HTTP❌ Must be enabled via WebApps (Router Console)Bundled webapp
i2pd (C++ implementation)https://127.0.0.1:7650/HTTPS✅ Enabled by defaultLegacy plugin behavior
在 Java I2P 的情况下，您必须前往 **Router Console → WebApps → I2PControl** 并启用它（设置为自动启动）。一旦激活，所有方法都要求您首先进行身份验证并接收会话令牌。

2. JSON-RPC 格式

所有请求都遵循 JSON-RPC 2.0 结构：

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "MethodName",
  "params": {
    /* named parameters */
  }
}

成功的响应包含一个 result 字段；失败时，会返回一个 error 对象：

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": { /* data */ }
}

或

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32001,
    "message": "Invalid password"
  }
}

3. 认证流程

请求（身份验证）

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "1",
        "method": "Authenticate",
        "params": {
          "API": 1,
          "Password": "itoopie"
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

成功响应

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "Token": "a1b2c3d4e5",
    "API": 1
  }
}

您必须在所有后续请求的 params 中包含该 Token。

4. 方法和端点

4.1 RouterInfo

获取关于 router 的关键遥测数据。

请求示例

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "2",
        "method": "RouterInfo",
        "params": {
          "Token": "a1b2c3d4e5",
          "i2p.router.version": "",
          "i2p.router.status": "",
          "i2p.router.net.status": "",
          "i2p.router.net.tunnels.participating": "",
          "i2p.router.net.bw.inbound.1s": "",
          "i2p.router.net.bw.outbound.1s": ""
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

响应字段 (result) 根据官方文档 (GetI2P)： - i2p.router.status (String) — 人类可读的状态 - i2p.router.uptime (long) — 毫秒数（或旧版 i2pd 的字符串） :contentReference[oaicite:0]{index=0} - i2p.router.version (String) — 版本字符串 :contentReference[oaicite:1]{index=1} - i2p.router.net.bw.inbound.1s, i2p.router.net.bw.inbound.15s (double) — 入站带宽，单位 B/s :contentReference[oaicite:2]{index=2} - i2p.router.net.bw.outbound.1s, i2p.router.net.bw.outbound.15s (double) — 出站带宽，单位 B/s :contentReference[oaicite:3]{index=3} - i2p.router.net.status (long) — 数字状态码（见下方枚举） :contentReference[oaicite:4]{index=4} - i2p.router.net.tunnels.participating (long) — 参与的 tunnel 数量 :contentReference[oaicite:5]{index=5} - i2p.router.netdb.activepeers, fastpeers, highcapacitypeers (long) — netDB 节点统计 :contentReference[oaicite:6]{index=6} - i2p.router.netdb.isreseeding (boolean) — 是否正在进行重新播种 :contentReference[oaicite:7]{index=7} - i2p.router.netdb.knownpeers (long) — 已知节点总数 :contentReference[oaicite:8]{index=8}

状态码枚举 (i2p.router.net.status)

CodeMeaning
0OK
1TESTING
2FIREWALLED
3HIDDEN
4WARN_FIREWALLED_AND_FAST
5WARN_FIREWALLED_AND_FLOODFILL
6WARN_FIREWALLED_WITH_INBOUND_TCP
7WARN_FIREWALLED_WITH_UDP_DISABLED
8ERROR_I2CP
9ERROR_CLOCK_SKEW
10ERROR_PRIVATE_TCP_ADDRESS
11ERROR_SYMMETRIC_NAT
12ERROR_UDP_PORT_IN_USE
13ERROR_NO_ACTIVE_PEERS_CHECK_CONNECTION_AND_FIREWALL
14ERROR_UDP_DISABLED_AND_TCP_UNSET
---

4.2 GetRate

用于在给定时间窗口内获取速率指标（例如带宽、tunnel 成功率）。

请求示例

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "3",
        "method": "GetRate",
        "params": {
          "Token": "a1b2c3d4e5",
          "Stat": "bw.combined",
          "Period": 60000
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

示例响应

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "Rate": 12345.67
  }
}

4.3 RouterManager

执行管理操作。

允许的参数 / 方法 - Restart, RestartGraceful - Shutdown, ShutdownGraceful - Reseed, FindUpdates, Update :contentReference[oaicite:10]{index=10}

请求示例

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "4",
        "method": "RouterManager",
        "params": {
          "Token": "a1b2c3d4e5",
          "Restart": true
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

成功响应

{
  "jsonrpc": "2.0",
  "id": "4",
  "result": {
    "Restart": null
  }
}

4.4 网络设置

获取或设置网络配置参数（端口、upnp、带宽共享等）

请求示例（获取当前值）

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "5",
        "method": "NetworkSetting",
        "params": {
          "Token": "a1b2c3d4e5",
          "i2p.router.net.ntcp.port": null,
          "i2p.router.net.ssu.port": null,
          "i2p.router.net.bw.share": null,
          "i2p.router.net.upnp": null
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

示例响应

{
  "jsonrpc": "2.0",
  "id": "5",
  "result": {
    "i2p.router.net.ntcp.port": "1234",
    "i2p.router.net.ssu.port": "5678",
    "i2p.router.net.bw.share": "50",
    "i2p.router.net.upnp": "true",
    "SettingsSaved": true,
    "RestartNeeded": false
  }
}

注意：i2pd 2.41 之前的版本可能返回数字类型而不是字符串——客户端应该处理两种类型。:contentReference[oaicite:11]{index=11}

4.5 高级设置

允许操作内部 router 参数。

请求示例

curl -s -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": "6",
        "method": "AdvancedSettings",
        "params": {
          "Token": "a1b2c3d4e5",
          "Set": {
            "router.sharePercentage": "75",
            "i2np.flushInterval": "6000"
          }
        }
      }' \
  http://127.0.0.1:7657/jsonrpc/

响应示例

{
  "jsonrpc": "2.0",
  "id": "6",
  "result": {
    "Set": {
      "router.sharePercentage": "75",
      "i2np.flushInterval": "6000"
    }
  }
}

5. 错误代码

标准 JSON-RPC2 错误代码

CodeMeaning
-32700JSON parse error
-32600Invalid request
-32601Method not found
-32602Invalid parameters
-32603Internal error
### I2PControl 特定错误代码
CodeMeaning
-32001Invalid password provided
-32002No authentication token presented
-32003Authentication token doesn't exist
-32004The provided authentication token was expired and will be removed
-32005The version of the I2PControl API used wasn't specified, but is required to be specified
-32006The version of the I2PControl API specified is not supported by I2PControl
---

6. 使用方法与最佳实践

  • 始终包含 Token 参数（除了进行身份验证时）。
  • 首次使用时更改默认密码（itoopie）。
  • 对于 Java I2P，确保通过 WebApps 启用 I2PControl webapp。
  • 准备应对细微差异：某些字段可能是数字或字符串，具体取决于 I2P 版本。
  • 为显示友好的输出换行长状态字符串。

Was this page helpful?