美化项目与AI网关文档

README.md

@@ -6,12 +6,14 @@
 
 **自托管的 OCI 多租户管理面板与 GenAI 兼容网关**
 
-![Release](https://img.shields.io/github/v/release/wangdefaa/oci-portal?display_name=tag)
-![Go](https://img.shields.io/badge/Go-1.26.5-00ADD8?logo=go&logoColor=white)
-![Docker](https://img.shields.io/badge/Docker-amd64%20%7C%20arm64-2496ED?logo=docker&logoColor=white)
-![License](https://img.shields.io/badge/License-MIT-blue)
+[![Release](https://img.shields.io/github/v/release/wangdefaa/oci-portal?display_name=tag)](https://github.com/wangdefaa/oci-portal/releases/latest)
+[![Go](https://img.shields.io/badge/Go-1.26.5-00ADD8?logo=go&logoColor=white)](go.mod)
+[![Docker](https://img.shields.io/badge/Docker-amd64%20%7C%20arm64-2496ED?logo=docker&logoColor=white)](docker-compose.yml)
+[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
 
-[快速开始](#快速开始) · [核心能力](#核心能力) · [生产部署](#生产部署) · [AI 网关](#ai-网关) · [开发](#开发)
+[界面预览](#界面预览) · [核心能力](#核心能力) · [快速开始](#快速开始) · [生产部署](#生产部署) · [AI 网关](#ai-网关) · [开发](#开发)
+
+[AI 网关文档](docs/AI网关.md) · [OpenAPI](docs/swagger.yaml) · [更新日志](CHANGELOG.md) · [前端仓库](https://github.com/wangdefaa/oci-portal-dash)
 
 </div>
 
@@ -21,27 +23,36 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
 
 ## 界面预览
 
-| 总览 | 登录 |
-| --- | --- |
-| ![总览](docs/assets/screenshot-overview.png) | ![登录](docs/assets/screenshot-signin.png) |
+<p align="center">
+  <img src="docs/assets/screenshot-overview.png" width="960" alt="OCI Portal 总览">
+</p>
 
-| 租户 | 任务 |
-| --- | --- |
-| ![租户](docs/assets/screenshot-tenants.png) | ![任务](docs/assets/screenshot-tasks.png) |
+<details>
+<summary><strong>展开更多界面截图</strong></summary>
 
-| AI 网关 | 通知设置 |
+| 登录 | 租户 |
 | --- | --- |
-| ![AI 网关](docs/assets/screenshot-ai-gateway.png) | ![通知设置](docs/assets/screenshot-settings-notify.png) |
+| ![登录](docs/assets/screenshot-signin.png) | ![租户](docs/assets/screenshot-tenants.png) |
+
+| 任务 | AI 网关 |
+| --- | --- |
+| ![任务](docs/assets/screenshot-tasks.png) | ![AI 网关](docs/assets/screenshot-ai-gateway.png) |
+
+| 通知设置 |
+| --- |
+| ![通知设置](docs/assets/screenshot-settings-notify.png) |
+
+</details>
 
 ## 核心能力
 
-- **租户与区域**：集中管理多份 OCI API Key，支持分组、批量测活、账户画像、订阅区域缓存与区域切换；私钥和口令使用 AES-256-GCM 加密落库
-- **计算、网络与存储**：实例创建与电源操作、公网 IP、IPv6、VNIC、串行控制台连接，VCN / 子网 / 安全列表，引导卷与块存储挂载，限额和成本查询
-- **自动化任务**：抢机、租户测活、成本同步、AI 渠道探测四类 cron 任务，提供执行日志、重叠执行防护、熔断与结果通知
-- **网页控制台**：浏览器内使用 xterm 串行终端和 noVNC，通过 OCI 控制台连接建立两跳 SSH 隧道
-- **身份与审计**：IAM 用户、MFA、API Key、密码策略、SAML 身份提供商、通知收件人和多 Identity Domain 管理；OCI Audit 事件可经 Service Connector Hub 与 Notifications 回传，关键事件按类别通过「云端事件」通知推送
-- **通知与安全**：Telegram、Webhook、ntfy、Bark、SMTP 五类渠道；JWT、bcrypt、TOTP、OIDC / GitHub 登录、登录锁定、IP 限速、会话撤销和系统操作审计
-- **AI 网关**：提供 OpenAI Responses、Chat Completions、Embeddings 与 Anthropic Messages 兼容接口，支持渠道分组、加权路由、熔断探测、模型黑白名单、密钥管理和调用日志
+| 能力域 | 覆盖范围 |
+| --- | --- |
+| **租户与云资源** | 多 OCI API Key、分组、批量测活、账户画像、订阅区域缓存与切换；实例创建与电源操作、VNIC、公网 IP、IPv6、VCN、安全列表、引导卷、块存储挂载、限额与成本查询 |
+| **自动化与控制台** | 抢机、租户测活、成本同步、AI 渠道探测；执行日志、重叠防护、熔断与结果通知；xterm 串行终端、noVNC 和 OCI 控制台连接两跳 SSH 隧道 |
+| **身份与审计** | IAM 用户、MFA、API Key、密码策略、SAML、通知收件人与多 Identity Domain；通过 Service Connector Hub 与 Notifications 接收并分类推送 OCI Audit 事件 |
+| **通知与安全** | Telegram、Webhook、ntfy、Bark、SMTP；AES-256-GCM、JWT、bcrypt、TOTP、OIDC / GitHub 登录、登录锁定、IP 限速、会话撤销和操作审计 |
+| **AI 网关** | OpenAI Responses、Chat Completions、Embeddings 与 Anthropic Messages；渠道分组、加权路由、熔断探测、模型治理、密钥管理和调用日志 |
 
 ## 运行形态
 
@@ -57,7 +68,9 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-默认推荐 SQLite 单实例部署。MySQL 和 PostgreSQL 适配仍属 experimental，不应据此推断服务支持多副本并发运行。
+> [!NOTE]
+> 默认推荐 SQLite 单实例部署。MySQL 和 PostgreSQL 适配仍属 experimental，
+> 不应据此推断服务支持多副本并发运行。
 
 ## 快速开始
 
@@ -65,6 +78,10 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
 
 前置条件：Docker、Docker Compose v2、OpenSSL。
 
+> [!CAUTION]
+> `.env` 中的 `DATA_KEY` 用于解密 OCI 私钥、口令和渠道凭据。首次生成后必须长期
+> 保存；升级或重装时不要覆盖，否则已有密文将无法恢复。
+
 1. 克隆仓库并生成一份需要长期保存的 `.env`：
 
    ```bash
@@ -79,19 +96,27 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
    chmod 600 .env
    ```
 
-2. 准备数据目录并启动：
+2. 准备数据目录：
 
    ```bash
    mkdir -p data
+   ```
 
-   # Linux bind mount 需要让镜像内的 nonroot 用户（uid 65532）可写。
+   Linux 使用 bind mount 时，需要让镜像内的 nonroot 用户（uid `65532`）可写；
+   Docker Desktop 用户通常不需要执行：
+
+   ```bash
    sudo chown 65532:65532 data
+   ```
 
+3. 启动并检查状态：
+
+   ```bash
    docker compose up -d
    docker compose ps
    ```
 
-3. 查看初始管理员密码并登录：
+4. 查看初始管理员密码并登录：
 
    ```bash
    grep '^ADMIN_PASSWORD=' .env
@@ -99,7 +124,14 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
 
    访问 `http://127.0.0.1:18888`，默认用户名为 `admin`。
 
-> `DATA_KEY` 用于解密数据库中的 OCI 私钥、口令和渠道凭据。它只能生成一次并持续复用；丢失或更换后，已有密文无法恢复。请将 `.env` 与 `data/oci-portal.db` 一起备份。
+   启动异常时查看最近日志：
+
+   ```bash
+   docker compose logs --tail=100 oci-portal
+   ```
+
+> [!TIP]
+> 请将 `.env` 与 `data/oci-portal.db` 成对备份；恢复时两者必须匹配。
 
 ### 二进制运行
 
@@ -107,6 +139,8 @@ Release 提供 Linux amd64 / arm64 二进制。以下以 amd64 为例；arm64
 
 ```bash
 curl -fLO https://github.com/wangdefaa/oci-portal/releases/latest/download/oci-portal-server-linux-amd64
+curl -fLO https://github.com/wangdefaa/oci-portal/releases/latest/download/SHA256SUMS
+grep 'oci-portal-server-linux-amd64$' SHA256SUMS | sha256sum -c -
 chmod +x oci-portal-server-linux-amd64
 
 # 复用上文生成并妥善保存的 .env。
@@ -142,7 +176,9 @@ CGO_ENABLED=0 go build -trimpath -o bin/oci-portal-server ./cmd/server
 
 ## 生产部署
 
-服务本身只提供 HTTP。除本机试用外，应保持服务仅监听回环地址或容器内部网络，并由 TLS 反向代理提供 HTTPS；否则管理员密码、JWT、AI 密钥和租户凭据会经明文连接传输。
+> [!WARNING]
+> 服务本身只提供 HTTP。除本机试用外，应仅监听回环地址或容器内部网络，并由
+> TLS 反向代理提供 HTTPS；否则管理员密码、JWT、AI 密钥和租户凭据会经明文传输。
 
 ### Caddy
 
@@ -229,29 +265,31 @@ OpenAPI 文件随仓库维护：[`docs/swagger.yaml`](docs/swagger.yaml) · [`do
 
 ### 环境变量
 
-| 变量 | 必填 | 默认值 | 说明 |
+| 变量 | 使用条件 | 默认值 | 说明 |
 | --- | :---: | --- | --- |
-| `DATA_KEY` | 是 | — | 敏感字段加密主密钥；必须持久保存，不能随意轮换 |
-| `JWT_SECRET` | 是 | — | JWT 签名密钥；更换会使已有登录令牌失效 |
-| `ADMIN_USERNAME` | 否 | `admin` | 初始管理员用户名 |
+| `DATA_KEY` | 必填 | — | 敏感字段加密主密钥；必须持久保存，不能随意轮换 |
+| `JWT_SECRET` | 必填 | — | JWT 签名密钥；更换会使已有登录令牌失效 |
+| `ADMIN_USERNAME` | 可选 | `admin` | 初始管理员用户名 |
 | `ADMIN_PASSWORD` | 首次启动 | — | 仅在数据库无用户时创建管理员，不会重置已有密码 |
-| `ADDR` | 否 | `:8080` | HTTP 监听地址 |
-| `DB_DRIVER` | 否 | `sqlite` | `sqlite` / `mysql` / `postgres`；后两者为 experimental |
+| `ADDR` | 可选 | `:8080` | HTTP 监听地址 |
+| `DB_DRIVER` | 可选 | `sqlite` | `sqlite` / `mysql` / `postgres`；后两者为 experimental |
 | `DB_PATH` | SQLite | `oci-portal.db` | SQLite 文件路径 |
-| `DB_DSN` | 外部数据库 | — | MySQL 需 `parseTime=True`；不要在日志或文档中暴露凭据 |
-| `PUBLIC_URL` | 否 | — | 面板公网基址，作为 OAuth 回调和日志回传引导的回退值 |
-| `TZ` | 否 | 系统时区 | cron 表达式的解释时区；容器示例使用 `Asia/Shanghai` |
-| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 否 | — | Go 标准出站代理变量；面板内显式代理配置优先用于对应业务 |
-| `SWAGGER` | 否 | 关闭 | 设为 `1` 时开放 Swagger UI |
-| `GIN_MODE` | 否 | `release` | `debug` / `release` |
+| `DB_DSN` | MySQL / PostgreSQL | — | MySQL 需 `parseTime=True`；不要在日志或文档中暴露凭据 |
+| `PUBLIC_URL` | 可选 | — | 面板公网基址，作为 OAuth 回调和日志回传引导的回退值 |
+| `TZ` | 可选 | 系统时区 | cron 表达式的解释时区；容器示例使用 `Asia/Shanghai` |
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 可选 | — | Go 标准出站代理变量；面板内显式代理配置优先用于对应业务 |
+| `SWAGGER` | 可选 | 关闭 | 设为 `1` 时开放 Swagger UI |
+| `GIN_MODE` | 可选 | `release` | `debug` / `release` |
 
 ## 升级与备份
 
-- 升级前同时备份 `.env` 和数据库；SQLite Compose 部署的数据文件为 `data/oci-portal.db`
-- 保持 `DATA_KEY` 不变；只恢复数据库而没有原密钥，敏感字段无法解密
-- 服务启动时会自动执行数据库迁移；跨版本升级前先阅读 [CHANGELOG](CHANGELOG.md)
-- Compose 部署使用 `docker compose pull && docker compose up -d` 更新镜像
-- OCI API Key 应遵循最小权限原则；生产环境保持 Swagger 关闭并限制管理面访问来源
+1. 阅读 [CHANGELOG](CHANGELOG.md)，确认目标版本的行为变化。
+2. 备份 `.env` 和数据库。SQLite Compose 部署建议先停止服务，再复制
+   `data/oci-portal.db`，避免在线复制产生不一致快照。
+3. 保持原 `DATA_KEY` 不变；只有数据库而没有对应密钥时，敏感字段无法解密。
+4. Compose 部署执行 `docker compose pull`，再执行 `docker compose up -d`；服务启动时
+   会自动完成数据库迁移。
+5. 生产环境保持 Swagger 关闭、限制管理面访问来源，并为 OCI API Key 配置最小权限。
 
 ## 开发