# 密码库 API

> 此模块使用**独立私人密钥**（非通用 apiToken）  
> 在 `/my/passwords` 页面生成，支持设置最大读取次数，超限后自动失效  
> ```bash
> PRIVATE_KEY="你生成的私人密钥"
> ```
> **注意：** 生成/删除私钥仅支持浏览器 session，不支持 curl

---

## 私人密钥管理 `/api/my/private-keys`

> 仅支持浏览器 session，不能用 curl 调用

```
GET    /api/my/private-keys          # 列出所有密钥
POST   /api/my/private-keys          # 生成新密钥（token 仅返回一次，立即保存）
DELETE /api/my/private-keys/:id      # 删除密钥（立即失效）
```

**POST 字段**

| 字段 | 必填 | 说明 |
|------|------|------|
| maxReads | ✓ | 最大读取次数，达到后密钥自动删除 |
| label | | 备注名 |

> 密钥达到 `maxReads` 后自动失效并删除。浏览密码列表不消耗次数，读取明文才消耗。

---

## 密码条目 `/api/my/passwords`

> **PUT 行为：整体替换**——不传的字段会被清空（title、password 为必填）。

```bash
# 浏览列表（不消耗次数）
curl "https://octohz.com/api/my/passwords" -H "Authorization: Bearer $PRIVATE_KEY"

# 读取明文（消耗 1 次）
curl "https://octohz.com/api/my/passwords/5" -H "Authorization: Bearer $PRIVATE_KEY"

# 新建
curl -X POST "https://octohz.com/api/my/passwords" \
  -H "Authorization: Bearer $PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Gmail","username":"user@gmail.com","password":"mypassword","url":"https://mail.google.com"}'

# 更新（整体替换，需传入所有要保留的字段）
curl -X PUT "https://octohz.com/api/my/passwords/1" \
  -H "Authorization: Bearer $PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Gmail","password":"newpassword","username":"user@gmail.com","url":"https://mail.google.com"}'

# 删除
curl -X DELETE "https://octohz.com/api/my/passwords/1" -H "Authorization: Bearer $PRIVATE_KEY"
```

**POST/PUT 字段**

| 字段 | 必填 | 说明 |
|------|------|------|
| title | ✓ | 条目名称 |
| password | ✓ | 密码明文（加密存储） |
| username | | 用户名 |
| url | | 关联网址 |
| notes | | 备注 |
| groupId | | 分组 ID |

---

## 主机管理 `/api/my/hosts`

共用密码库私人密钥。  
> **PUT 行为：局部更新**——只传要改的字段，不传的字段保留原值。

```bash
# 浏览列表（不消耗次数）
curl "https://octohz.com/api/my/hosts" -H "Authorization: Bearer $PRIVATE_KEY"

# 读取完整凭据（消耗 1 次）
curl "https://octohz.com/api/my/hosts/3" -H "Authorization: Bearer $PRIVATE_KEY"

# 新建
curl -X POST "https://octohz.com/api/my/hosts" \
  -H "Authorization: Bearer $PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"香港 VPS","hostType":"virtual","os":"Ubuntu 24.04","location":"香港","publicIp":"1.2.3.4","rootPassword":"mypassword","panelName":"1Panel","panelUrl":"http://1.2.3.4:8888"}'

# 更新（局部更新，只传要改的字段）
curl -X PUT "https://octohz.com/api/my/hosts/1" \
  -H "Authorization: Bearer $PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rootPassword":"newpassword"}'

# 删除
curl -X DELETE "https://octohz.com/api/my/hosts/1" -H "Authorization: Bearer $PRIVATE_KEY"
```

**字段**

| 字段 | 必填 | 说明 |
|------|------|------|
| name | ✓ | 主机名称 |
| hostType | | `virtual`（默认）/ `physical` |
| os | | 系统（如 `Ubuntu 24.04`） |
| location | | 地区（如 `香港`） |
| cpu | | CPU 规格（如 `2核`） |
| memory | | 内存（如 `4GB`） |
| disk | | 磁盘（如 `40GB SSD`） |
| publicIp | | 公网 IP |
| privateIp | | 内网 IP |
| sshPort | | SSH 端口（默认 22） |
| rootUser | | SSH 用户（默认 `root`） |
| rootPassword | | SSH 密码（加密存储） |
| panelName | | 面板名称（如 `1Panel`） |
| panelUrl | | 面板地址 |
| panelUser | | 面板用户名 |
| panelPassword | | 面板密码（加密存储） |
| groupId | | 分组 ID |
| notes | | 备注 |

---

## API 密钥管理 `/api/my/apis`

共用密码库私人密钥。  
> **PUT 行为：局部更新**——只传要改的字段，不传的字段保留原值（包括 apiKey）。

```bash
# 浏览列表（不消耗次数）
curl "https://octohz.com/api/my/apis" -H "Authorization: Bearer $PRIVATE_KEY"

# 读取明文（消耗 1 次）
curl "https://octohz.com/api/my/apis/1" -H "Authorization: Bearer $PRIVATE_KEY"

# 新建
curl -X POST "https://octohz.com/api/my/apis" \
  -H "Authorization: Bearer $PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"OpenAI","apiKey":"sk-xxx","baseUrl":"https://api.openai.com/v1","model":"gpt-4o"}'

# 更新（局部更新，只传要改的字段；不传 apiKey 则保留原值）
curl -X PUT "https://octohz.com/api/my/apis/1" \
  -H "Authorization: Bearer $PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini"}'

# 删除
curl -X DELETE "https://octohz.com/api/my/apis/1" -H "Authorization: Bearer $PRIVATE_KEY"
```

**POST/PUT 字段**

| 字段 | 必填 | 说明 |
|------|------|------|
| name | ✓ | API 名称 |
| apiKey | ✓（POST）| Key 明文（加密存储，PUT 不传保留原值） |
| siteUrl | | 平台网址 |
| planType | | 套餐类型（如 `Pro`） |
| baseUrl | | Base URL |
| model | | 默认模型 |
| notes | | 备注 |
| groupId | | 分组 ID |


---

**分类**：Octohz 我的功能
**链接**：https://octohz.com/docs?doc=75