diff --git a/.obsidian/plugins/obsidian-git/data.json b/.obsidian/plugins/obsidian-git/data.json new file mode 100644 index 0000000..f5efe68 --- /dev/null +++ b/.obsidian/plugins/obsidian-git/data.json @@ -0,0 +1,75 @@ +{ + "commitMessage": "vault backup: {{date}}", + "autoCommitMessage": "vault backup: {{date}}", + "commitMessageScript": "", + "commitDateFormat": "YYYY-MM-DD HH:mm:ss", + "autoSaveInterval": 1, + "autoPushInterval": 0, + "autoPullInterval": 0, + "autoPullOnBoot": false, + "autoCommitGlobMode": "exclude", + "autoCommitGlobs": "", + "disablePush": false, + "pullBeforePush": true, + "squashCommitsBeforePush": false, + "disablePopups": false, + "showErrorNotices": true, + "disablePopupsForNoChanges": false, + "listChangedFilesInMessageBody": false, + "showStatusBar": true, + "updateSubmodules": false, + "syncMethod": "merge", + "rebaseAutoStash": "enabled", + "mergeStrategy": "none", + "customMessageOnAutoBackup": false, + "autoBackupAfterFileChange": false, + "treeStructure": false, + "gitServerPasswordSecret": "", + "refreshSourceControl": true, + "basePath": "", + "differentIntervalCommitAndPush": false, + "changedFilesInStatusBar": false, + "limitToVault": false, + "showedMobileNotice": true, + "refreshSourceControlTimer": 7000, + "showBranchStatusBar": true, + "conflictResolutionMode": "both", + "setLastSaveToLastCommit": false, + "submoduleRecurseCheckout": false, + "gitDir": "", + "showFileMenu": true, + "authorInHistoryView": "hide", + "dateInHistoryView": false, + "diffStyle": "split", + "diffTimeout": 50, + "autoStageOnEmptyIndex": true, + "hunks": { + "showSigns": false, + "hunkCommands": false, + "statusBar": "disabled" + }, + "lineAuthor": { + "show": false, + "followMovement": "inactive", + "authorDisplay": "initials", + "showCommitHash": false, + "dateTimeFormatOptions": "date", + "dateTimeFormatCustomString": "YYYY-MM-DD HH:mm", + "dateTimeTimezone": "viewer-local", + "coloringMaxAge": "1y", + "colorNew": { + "r": 255, + "g": 150, + "b": 150 + }, + "colorOld": { + "r": 120, + "g": 160, + "b": 255 + }, + "textColorCss": "var(--text-muted)", + "ignoreWhitespace": false, + "lastShownAuthorDisplay": "initials", + "lastShownDateTimeFormatOptions": "date" + } +} \ No newline at end of file diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index 296fe37..6dbdfb3 100644 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -216,6 +216,8 @@ }, "active": "bf2a0beebbd3d1e9", "lastOpenFiles": [ + "工具相关/www.md", + "项目文档/徐工/蓝牙/徐工项目软件烧录文档.pdf.ldenc", "工具相关/CPA部署全流程.md", "工具相关/NewAPI搭建与上线完整实战指南.md", "AI/AI应用开发.md", @@ -247,13 +249,11 @@ "项目文档/同力/同力老项目蓝牙/蓝牙模块完整代码分析.md", "项目文档/同力/同力相关.md", "Pasted image 20261023184114.png", - "日志/2026/日志11月.md.tmp.27720.f36f27ede93a", "项目文档/徐工/语音.md", "项目文档/徐工/优化开机速度.md", "项目文档/徐工/蓝牙/bluetooth_git_summary.md", "项目文档/徐工/蓝牙/蓝牙模块流程概览.md", "项目文档/徐工/蓝牙/蓝牙模块开发熟悉手册.md", - "项目文档/徐工/徐工系统编译相关.md", "42d68e79e0122117fc941868202bfc9d.png", "项目文档/犀重/升级流程图.jpg", "工具学习/redmine_stats/tongli_stats.png", diff --git a/工具相关/www.md b/工具相关/www.md new file mode 100644 index 0000000..c3879d6 --- /dev/null +++ b/工具相关/www.md @@ -0,0 +1,320 @@ +# New API 专属大模型网关搭建与 HTTPS 上线全流程实战指南 + +> **实战环境记录** +> - **云服务器**：腾讯云新加坡轻量应用服务器（Ubuntu 24.04 LTS，2核 2G 内存，公网 IP：`43.156.118.130`） +> - **共存服务**：Xray Shadowsocks 代理服务（端口 `8388`，全程独立运行，互不干扰） +> - **域名提供商**：Spaceship（根域名：`trivoo.website`，网关二级子域名：`api.trivoo.website`） +> - **网关核心**：New API（官方镜像 `calciumion/new-api:latest`，Docker 容器化 + 内置 SQLite 持久化） +> - **反代与加密**：Nginx 反向代理 + Let's Encrypt 权威 SSL 证书（Certbot 自动化定时续期） + +--- + +## 目录 +- [一、全局架构与准备工作](#一全局架构与准备工作) +- [二、第一阶段：域名注册与 DNS 解析配置](#二第一阶段域名注册与-dns-解析配置) +- [三、第二阶段：云服务器防火墙安全配置](#三第二阶段云服务器防火墙安全配置) +- [四、第三阶段：New API 容器化部署](#四第三阶段new-api-容器化部署) +- [五、第四阶段：Nginx 反向代理与 SSL 证书自动化](#五第四阶段nginx-反向代理与-ssl-证书自动化) +- [六、第五阶段：New API 初始化与渠道配置](#六第五阶段new-api-初始化与渠道配置) +- [七、第六阶段：客户端接入与高频踩坑排错手册](#七第六阶段客户端接入与高频踩坑排错手册) +- [八、第七阶段：日常运维、安全加固与一键清理](#八第七阶段日常运维安全加固与一键清理) + +--- + +## 一、全局架构与准备工作 + +本方案采用**“单容器 SQLite + Nginx 本地反代 + Certbot 自动化证书”**的生产级架构： + +``` +[ 客户端 (Cline / Cherry Studio / 代码) ] + │ HTTPS (端口 443) + ▼ +[ Nginx 反向代理 (api.trivoo.website) ] ── (自动申请/更新 Let's Encrypt 证书) + │ HTTP (仅监听 127.0.0.1:3000，外部无法直连) + ▼ +[ New API 容器 (calciumion/new-api:latest) ] + │ + ┌─────────┴─────────┐ + ▼ ▼ +[ 官方 DeepSeek API ] [ 自定义第三方聚合上游 ] +``` + +### 核心设计优势： +1. **轻量省资源**：相比 PostgreSQL + Redis 的重型部署，内置 SQLite 单容器仅占几十兆内存，完美兼容 2G 内存低配服务器，与已有代理服务（如 Xray）和谐共存。 +2. **端口安全性**：New API 容器端口严格绑定在 `127.0.0.1:3000`，外部网络无法绕过 HTTPS 直接访问，防止明文直连与未授权嗅探。 +3. **流式传输优化**：Nginx 明确关闭 `proxy_buffering`，保障大模型打字机流式输出（SSE）流畅无卡顿。 + +--- + +## 二、第一阶段：域名注册与 DNS 解析配置 + +### 1. 域名选购（以 Spaceship 为例） +1. 访问 [Spaceship 官网](https://www.spaceship.com/) 并注册/登录账号； +2. 搜索低成本优质后缀（如 `.website`、`.top`、`.xyz` 等，首年特价通常仅约 6~10 元人民币）； +3. 选定域名（本次实战选定 `trivoo.website`，首年仅 7.88 元含 ICANN 认证工本费）； +4. 通过绑定的 **支付宝（Alipay）** 扫码付款完成购买。 +5. **重要防扣费设置**：购买完成后，在域名列表的 `Auto-renew` 列将开关拨至 **Off**，避免次年按原价自动续费。 + +### 2. 添加 DNS A 记录解析 +1. 在 Spaceship 控制台点击域名右侧的 **Advanced DNS ↗**； +2. 点击 **Add Record**（或点击下方小圆圈 `A`）： + - **Type**：`A` + - **Host**：`api`（即二级子域名，完整网址为 `api.trivoo.website`） + - **Value / Target IP**：`43.156.118.130`（你的云服务器公网 IP） + - **TTL**：保持默认或选择 `30 min` / `1 min` +3. 点击 **Add / Save** 保存，等待右侧出现绿色的 `ADDED` 提示。 + +--- + +## 三、第二阶段：云服务器防火墙安全配置 + +登录 [腾讯云轻量服务器控制台](https://console.cloud.tencent.com/lighthouse) -> 点击目标实例 -> **防火墙**，确保以下规则已放行： + +| 应用类型 | 协议 | 端口 | 策略 | 作用说明 | +| :--- | :--- | :--- | :--- | :--- | +| Linux 登录 | TCP | 22 | 允许 | SSH 远程登录维护 | +| HTTP | TCP | 80 | 允许 | Certbot 申请 SSL 证书及 HTTP-01 验证 | +| HTTPS | TCP | 443 | 允许 | 安全加密 Web 访问及客户端 API 调用 | +| 自定义 | TCP | 8388 | 允许 | 已有的 Xray / Shadowsocks 梯子服务 | + +> **安全注意**：不要在公网防火墙中开放 `3000` 端口。生产环境下 3000 端口只走服务器内部回环转发，所有外网流量统一由 443 端口接入。 + +--- + +## 四、第三阶段：New API 容器化部署 + +### 1. 登录服务器并切换 root 权限 +在本地终端执行： +```bash +ssh ubuntu@43.156.118.130 +sudo -i +``` +*(必须通过 `sudo -i` 确保提示符为 `root@...:~#`，避免因普通权限导致 Permission Denied)* + +### 2. 初始化目录并生成专属随机密钥 +```bash +# 创建持久化数据与日志目录 +mkdir -p /opt/new-api/data /opt/new-api/logs +cd /opt/new-api + +# 生成 64 位密码级随机安全会话密钥 +echo "SESSION_SECRET=$(openssl rand -hex 32)" > .env +chmod 600 .env +``` + +### 3. 编写安全生产型 docker-compose.yml +```bash +cat > /opt/new-api/docker-compose.yml <<'EOF' +services: + new-api: + image: calciumion/new-api:latest + container_name: new-api + restart: unless-stopped + command: --log-dir /app/logs + + # 严格绑定回环地址，禁止公网直连 3000 + ports: + - "127.0.0.1:3000:3000" + + volumes: + - ./data:/data + - ./logs:/app/logs + + environment: + - TZ=Asia/Shanghai + - ERROR_LOG_ENABLED=true + - BATCH_UPDATE_ENABLED=true + - NODE_NAME=new-api-sg-1 + - STREAMING_TIMEOUT=300 + - "SESSION_SECRET=${SESSION_SECRET:?未设置 SESSION_SECRET，请检查 .env}" + - SESSION_COOKIE_SECURE=true + - SESSION_COOKIE_TRUSTED_URL=https://api.trivoo.website + - TRUSTED_PROXIES=127.0.0.1,172.17.0.0/16 + + # 内存保护上限（防止高并发下拖垮同机代理服务） + mem_limit: 800m +EOF +``` + +### 4. 启动容器与状态检查 +```bash +cd /opt/new-api +docker compose up -d +docker ps +``` +回显中显示 `new-api` 状态为 `Up` 且端口为 `127.0.0.1:3000->3000/tcp` 即代表容器启动成功。 + +--- + +## 五、第四阶段：Nginx 反向代理与 SSL 证书自动化 + +### 1. 安装 Nginx 与 Certbot 证书套件 +```bash +apt update && apt install -y nginx certbot python3-certbot-nginx +``` + +### 2. 写入 Nginx 站点配置 +创建反向代理配置文件 `/etc/nginx/sites-available/api.trivoo.website`： +```bash +cat > /etc/nginx/sites-available/api.trivoo.website <<'EOF' +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} + +server { + listen 80; + server_name api.trivoo.website; + + # 允许大文件上传（如语音转录、多模态图片） + client_max_body_size 100m; + + location / { + proxy_pass http://127.0.0.1:3000; + proxy_http_version 1.1; + + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # WebSocket 协议支持（Realtime / Responses 升级通道） + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + + # 核心：关闭缓冲以支持打字机流式响应（SSE） + proxy_buffering off; + proxy_cache off; + proxy_read_timeout 1800s; + proxy_send_timeout 1800s; + } +} +EOF +``` + +### 3. 启用站点并检查语法 +```bash +ln -sf /etc/nginx/sites-available/api.trivoo.website /etc/nginx/sites-enabled/ +nginx -t && systemctl reload nginx +``` +*(必须看到 `syntax is ok` 与 `test is successful`)* + +### 4. 一键自动签发 Let's Encrypt 证书并启用 HTTPS +```bash +certbot --nginx -d api.trivoo.website --non-interactive --agree-tos -m admin@trivoo.website --redirect +``` +执行完毕后出现： +`Congratulations! You have successfully enabled HTTPS on https://api.trivoo.website` +此时证书已自动安装，并已创建 systemd 自动续期定时器。 + +--- + +## 六、第五阶段：New API 初始化与渠道配置 + +### 1. 首次访问与系统向导 +浏览器访问：`https://api.trivoo.website` +1. **数据库检查**：自动检测出 SQLite，直接点击「下一步」； +2. **管理员账户**：设定管理员用户名和高强度密码； +3. **完成初始化**：进入控制台主界面。 + +### 2. 接入官方渠道（以 DeepSeek 官方为例） +1. 左侧菜单栏点击 **「渠道」** -> 右上角 **「创建渠道」**； +2. **类型**：选择 `DeepSeek`； +3. **API 密钥**：填入 DeepSeek 官方以 `sk-` 开头的 API Key； +4. **模型**：点击快捷操作中的 **「填入相关模型」**，框内自动出现 `deepseek-chat` 与 `deepseek-reasoner` 标签； +5. 点击最底部 **「提交」**； +6. 在渠道列表中点击该卡片右上角的 **仪表盘图标（测速）**，出现绿色延迟（如 `554ms`）代表渠道通信成功。 + +### 3. 接入第三方自定义渠道（以 `apikey.fan` 聚合服务为例） +1. 点击 **「创建渠道」** -> 类型选 **`高级自定义`**（或 OpenAI 兼容）； +2. **API 地址**：填入服务商的基础网关地址（如 `https://api.apikey.fan`）； +3. **API 密钥**：填入该服务商提供的密钥； +4. **模型**：手动输入该上游支持的具体模型名（如 `gpt-5.6-terra`），**按回车确认生成标签**； +5. 点击提交并点击测试图标，验证连通性。 + +### 4. 生成调用令牌（分发密钥） +1. 左侧菜单栏点击 **「常规」 -> 「API 密钥」**（或「令牌」）； +2. 点击右上角 **「创建密钥」**； +3. 设定名称（如 `default-token`），额度设为无限或指定额度； +4. 提交后在列表中点击 **「复制」**，获取专属于该网关的 `sk-xxxx` 令牌。 + +--- + +## 七、第六阶段：客户端接入与高频踩坑排错手册 + +### 1. 客户端标准配置示例 + +在任何支持第三方 API 的客户端（如 Cline、NextChat、Cherry Studio、Chatbox 等）中配置： + +- **接口地址 / Base URL**：`https://api.trivoo.website/v1` +- **API Key**：填入后台生成的 `sk-xxxx` 令牌 +- **模型名称**：填入渠道中已有的有效模型（如 `deepseek-chat` 或 `gpt-5.6-terra`） + +--- + +### 2. 实战高频报错与精准排错对照 + +#### ❌ 错误 1：`404 Invalid URL (POST /v1/v1/messages)` +* **现象**：客户端报错 404，请求路径出现重复的 `/v1/v1`。 +* **原因**：部分遵循 Anthropic / Claude 协议的客户端（如某些版本的 Cline），内部会自动为地址补全 `/v1/messages`。如果你在配置的 Base URL 中包含了 `/v1`，拼接后就会变成 `/v1/v1/messages`。 +* **解决方案**：将客户端的 API 地址末尾的 `/v1` 删掉，改为 `https://api.trivoo.website`。 + +#### ❌ 错误 2：`503 No available channel for model xxx under group default` +* **现象**：客户端发起调用，返回 `model_not_found`。 +* **原因**：客户端发送的模型请求名称（例如 `gpt-5.6-terra`），在 New API 的所有可用渠道模型列表中都不存在。 +* **解决方案**： + - **方案 A（改客户端）**：将客户端的模型名称改为渠道真实支持的名字（如 `deepseek-chat`）； + - **方案 B（改网关重定向）**：在 New API 对应渠道编辑页中，点击「设置模型重定向」，将外部请求的 `gpt-5.6-terra` 重定向映射到后端的 `deepseek-chat`。 + +#### ❌ 错误 3：`Permission denied` / `No such file or directory` +* **现象**：在服务器终端执行 Docker 或 Nginx 配置命令时报错。 +* **原因**：新开的 SSH 会话默认处于普通用户 `ubuntu` 权限。 +* **解决方案**：执行命令前务必先输入 `sudo -i` 切换到 `root` 账户。 + +#### ❌ 错误 4：Spaceship 登录报 `Invalid username or password` +* **现象**：明明输入了正确邮箱和密码，却无法登录 Spaceship。 +* **原因**：Spaceship 强制要求在第一栏输入当初注册时设置的 **Username（用户名，如 `Beyond`）**，不支持直接使用邮箱登录。 +* **解决方案**：在注册邮件中查找用户名，使用纯用户名登录。 + +--- + +## 八、第七阶段：日常运维、安全加固与一键清理 + +### 1. 生产环境安全加固（必做） +* **关闭公开注册**： + 进入后台 `https://api.trivoo.website` -> **「系统设置」 -> 「登录注册」** -> 将 **「允许新用户注册」彻底关闭**。 + *(防止域名暴露在公网后被爬虫扫描并注册账号白嫖接口额度)* +* **SSL 自动续期确认**： + Certbot 已经注册了 systemd 定时任务，可通过以下命令测试自动续期机制： + ```bash + certbot renew --dry-run + ``` + +### 2. 日常启停与重启 +```bash +# 暂停 New API 网关（保留所有数据，释放 CPU/内存占用） +cd /opt/new-api && docker compose stop && systemctl stop nginx + +# 重新启动 New API 网关 +cd /opt/new-api && docker compose start && systemctl start nginx + +# 查看实时运行日志 +cd /opt/new-api && docker compose logs -f --tail=100 new-api +``` + +### 3. 一键卸载与彻底清理（恢复纯净服务器） +如果后续需要腾空服务器，执行以下步骤可在 1 分钟内完全清理痕迹，且**完全不影响服务器原有的代理与 SSH 服务**： + +```bash +# 1. 停止并销毁容器及持久化目录 +cd /opt/new-api && docker compose down +rm -rf /opt/new-api + +# 2. 卸载 Nginx 站点配置 +rm -f /etc/nginx/sites-enabled/api.trivoo.website /etc/nginx/sites-available/api.trivoo.website +systemctl reload nginx + +# 3. 删除 Let's Encrypt 证书记录（可选） +certbot delete --cert-name api.trivoo.website +``` +同时登录 Spaceship 域名控制台，将 `api.trivoo.website` 的 A 记录直接点击删除即可。