Beaver/beaver_project
6
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: 将项目从nano重命名为beaver并更新相关配置

Browse Source 
- 将所有环境变量前缀从NANO_改为BEAVER_
- 更新README.md文档内容，包括项目介绍、组件说明和快速开始指南
- 修改.gitignore文件，添加auth-portal运行时路径排除规则
- 更新app-instance镜像标签从nano/app-instance改为beaver/app-instance
- 增强技能安全检查器，支持工具前缀白名单功能
- 添加技能草稿重新检查安全性API端点
- 扩展证据选择器，收集工具调用名称用于技能学习
- 改进技能合成器，基于实际调用的工具生成工具提示
- 优化路由超时处理机制，增加重试逻辑
- 更新后端架构文档，添加可视化入口和基础概念说明
- 实现在WebSocket消息中传递工具迭代次数信息
This commit is contained in:
steven_li
2026-05-20 18:01:06 +08:00
parent 3b0af173cc
commit 9d6cde2d23
63 changed files with 4894 additions and 1596 deletions
Download Patch File Download Diff File Expand all files Collapse all files

574
域名配置指引.md
View File

@ -1,65 +1,34 @@
# nano_project 域名配置指引
# Beaver Project 域名配置指引
这份文档专门解释一件事：
这份文档说明如何从本机测试域名 `127.0.0.1.nip.io` 切换到正式域名。
- 如果你不用 `127.0.0.1.nip.io`
- 想换成自己的正式域名
- 应该怎么理解、怎么配、该改哪些地方
核心结论：
先说最重要的结论：
- DNS 只负责把域名解析到 IP。
- DNS 不负责端口。
- `auth-portal` 和用户实例建议使用不同域名。
- 正式环境建议用外层 Nginx、Caddy、Traefik 或云负载均衡监听 `80/443`。
- `router-proxy` 必须收到原始 `Host` 头，才能按实例域名转发。
- `DNS` 只管把域名解析到 `IP`
- `端口` 不归 DNS 管
- 所以“域名配到哪个端口”本质上是反向代理或公网入口层在处理
## 1. 默认端口职责
也就是说：
| 端口 | 组件 | 是否建议公网直接暴露 |
| --- | --- | --- |
| `3081` | `auth-portal`，用户登录和注册入口 | 可以，或由外层代理转发 |
| `8088` | `router-proxy`，所有实例统一入口 | 可以，或由外层代理转发 |
| `8090` | `deploy-control`，内部部署控制面 | 不建议 |
| `19090` | `authz-service`，内部鉴权服务 | 不建议 |
- 域名解析本身，是项目外部的事情
- 但项目里生成出来的实例地址、门户地址，又会依赖你填的域名
正式部署时，通常由外层入口暴露 `80/443`，再转发到本机端口：
所以这件事是：
```text
portal.example.com -> 127.0.0.1:3081
*.apps.example.com -> 127.0.0.1:8088
```
- 一半在系统外
- 一半和系统配置有关
## 2. 推荐域名规划
---
## 1. 先理解这套系统里每个端口是干什么的
当前默认端口职责：
- `3081`
- `auth-portal`
- 用户注册、登录入口
- `8088`
- `router-proxy`
- 所有用户实例统一入口
- `8090`
- `deploy-control`
- 内部控制面
- `19090`
- `authz-service`
- 内部鉴权服务
正常公网暴露建议：
- 暴露 `3081`
- 暴露 `8088`
- 不要直接暴露 `8090`
- 不要直接暴露 `19090`
---
## 2. 推荐的域名规划
最推荐这样分：
- `portal.example.com`
- 给登录/注册页
- `*.apps.example.com`
- 给用户实例
这样用户最终访问会像：
推荐拆成两个域名空间：
```text
https://portal.example.com
@ -67,168 +36,98 @@ https://alice.apps.example.com
https://bob.apps.example.com
```
其中：
含义：
- `portal.example.com` 走 `auth-portal`
- `alice.apps.example.com` 走 `router-proxy`
- `portal.example.com` 给 `auth-portal`
- `*.apps.example.com` 给 `router-proxy`
- 每个实例使用一个子域名，例如 `alice.apps.example.com`
---
不要把门户和实例混在同一个 Host 上。`router-proxy` 是实例入口，`auth-portal` 是认证入口，两者职责不同。
## 3. 只配 DNS 还不够
## 3. DNS 要怎么配
很多人最容易误解的是：
假设服务器公网 IP 是 `203.0.113.10`。
“我把域名解析到服务器 IP，就等于已经配好了”
这不对。
你还要解决：
- 用户访问 `80/443` 时，流量先进谁
- 谁把流量转到 `3081`
- 谁把流量转到 `8088`
所以正式域名一般至少要有两层：
### 第一层：DNS
例如：
- `portal.example.com` -> 服务器公网 IP
- `apps.example.com` -> 服务器公网 IP
- `*.apps.example.com` -> 服务器公网 IP
### 第二层：公网反向代理
例如用：
- Nginx
- Caddy
- Traefik
- 云负载均衡
它负责：
- 监听公网 `80/443`
- 根据域名把请求转发到本机不同端口
---
## 4. 最直接的映射关系
如果你先不做 HTTPS，只做最基础的 HTTP：
- `portal.example.com` -> 转发到 `127.0.0.1:3081`
- `*.apps.example.com` -> 转发到 `127.0.0.1:8088`
也就是：
DNS 记录：
```text
portal.example.com -> auth-portal -> 3081
*.apps.example.com -> router-proxy -> 8088
portal.example.com A 203.0.113.10
apps.example.com A 203.0.113.10
*.apps.example.com A 203.0.113.10
```
如果你的 DNS 服务商支持 CNAME，也可以让通配子域名 CNAME 到一个已有 A 记录，但最终结果仍然必须能解析到服务器入口 IP。
注意：
- `router-proxy` 是靠 `Host` 头识别具体实例的
- 所以必须把原始 Host 透传过去
- `*.apps.example.com` 用于实例子域名。
- `apps.example.com` 本身不是必须给用户访问，但建议也解析到同一入口，方便证书和排查。
- DNS 不会决定 `3081`、`8088`、`443` 这些端口。
---
## 4. 外层反向代理要做什么
## 5. 这个项目内部哪些值要改
外层代理负责：
如果你要从 `127.0.0.1.nip.io` 换成正式域名，至少要改这些：
- 监听公网 `80/443`
- 处理 TLS 证书
- 按 Host 转发请求
- 透传原始 Host
- 支持 WebSocket upgrade
### 本机部署变量里
把：
```bash
export NANO_BASE_DOMAIN=127.0.0.1.nip.io
```
改成：
```bash
export NANO_BASE_DOMAIN=apps.example.com
```
这样以后新创建的实例 URL 才会变成：
最小映射：
```text
http://alice.apps.example.com:8088
portal.example.com -> http://127.0.0.1:3081
*.apps.example.com -> http://127.0.0.1:8088
```
如果你后面还有外层 `80/443` 代理，不想让用户看到 `:8088`，那还需要额外调整入口层做无端口访问转发。
`*.apps.example.com` 转发到 `router-proxy` 时必须保留原始 Host，例如：
### `deploy-control` 里实际影响实例地址的变量
```nginx
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
```
它们是：
否则 `router-proxy` 无法知道请求属于哪个实例。
- `DEPLOY_PUBLIC_SCHEME`
- `DEPLOY_PUBLIC_BASE_DOMAIN`
- `DEPLOY_PUBLIC_PORT`
## 5. 项目内部要改哪些变量
例如：
实例公网地址由 `deploy-control` 里的这些变量决定：
| 变量 | 含义 |
| --- | --- |
| `DEPLOY_PUBLIC_SCHEME` | 对外协议，`http` 或 `https` |
| `DEPLOY_PUBLIC_BASE_DOMAIN` | 实例基域名，例如 `apps.example.com` |
| `DEPLOY_PUBLIC_HOST_TEMPLATE` | Host 生成模板，默认 `{slug}.{base_domain}` |
| `DEPLOY_PUBLIC_PORT` | 对外端口，`80` / `443` 会在生成 URL 时省略 |
本机测试：
```bash
-e DEPLOY_PUBLIC_SCHEME="https" \
-e DEPLOY_PUBLIC_BASE_DOMAIN="apps.example.com" \
-e DEPLOY_PUBLIC_PORT="443" \
export BEAVER_BASE_DOMAIN=127.0.0.1.nip.io
```
或者如果你暂时还是明文 HTTP：
`deploy-control`：
```bash
-e DEPLOY_PUBLIC_SCHEME="http" \
-e DEPLOY_PUBLIC_BASE_DOMAIN="apps.example.com" \
-e DEPLOY_PUBLIC_BASE_DOMAIN="$BEAVER_BASE_DOMAIN" \
-e DEPLOY_PUBLIC_PORT="8088" \
```
---
## 6. 什么时候可以把端口从 URL 里去掉
如果你希望用户访问：
生成实例地址：
```text
https://alice.apps.example.com
http://alice.127.0.0.1.nip.io:8088
```
而不是：
```text
http://alice.apps.example.com:8088
```
那你需要满足这两个条件：
1. 外层已经有监听 `80/443` 的反向代理
2. 它已经把 `*.apps.example.com` 转发到本机 `8088`
这时项目内部就应该写：
正式 HTTPS：
```bash
DEPLOY_PUBLIC_SCHEME=https
DEPLOY_PUBLIC_BASE_DOMAIN=apps.example.com
DEPLOY_PUBLIC_PORT=443
export BEAVER_BASE_DOMAIN=apps.example.com
```
或者很多时候你也可以直接在显示层隐藏默认端口概念，让用户只看标准 `https` 地址。
---
## 7. 一套推荐的正式域名方案
假设你有：
- 门户域名：`portal.example.com`
- 实例根域名：`apps.example.com`
推荐这样做：
### 项目内部
`deploy-control`：
```bash
@ -237,159 +136,200 @@ DEPLOY_PUBLIC_PORT=443
-e DEPLOY_PUBLIC_PORT="443" \
```
本机部署变量：
生成实例地址：
```bash
export NANO_BASE_DOMAIN=apps.example.com
```text
https://alice.apps.example.com
```
### 项目外部
前提是外层代理已经把 `*.apps.example.com:443` 转发到 `router-proxy:8088`。
## 6. 什么时候 URL 里可以不带端口
浏览器默认端口：
- `http` 默认 `80`
- `https` 默认 `443`
所以：
```bash
DEPLOY_PUBLIC_SCHEME=https
DEPLOY_PUBLIC_PORT=443
```
生成：
```text
https://alice.apps.example.com
```
而不是：
```text
https://alice.apps.example.com:443
```
如果你设置：
```bash
DEPLOY_PUBLIC_SCHEME=http
DEPLOY_PUBLIC_PORT=8088
```
生成：
```text
http://alice.apps.example.com:8088
```
因为 `8088` 不是 HTTP 默认端口。
## 7. 一套推荐生产配置
假设：
- 门户域名：`portal.example.com`
- 实例基域名：`apps.example.com`
- 外层代理负责 HTTPS
- 项目基础容器仍在同一台机器上通过 Docker 运行
部署变量：
```bash
export BEAVER_BASE_DOMAIN=apps.example.com
export BEAVER_AUTHZ_URL='http://beaver-authz-service:19090'
export BEAVER_DEPLOY_URL='http://beaver-deploy-control:8090'
```
`deploy-control`：
```bash
-e DEPLOY_PUBLIC_SCHEME="https" \
-e DEPLOY_PUBLIC_BASE_DOMAIN="apps.example.com" \
-e DEPLOY_PUBLIC_PORT="443" \
```
外层代理：
```text
portal.example.com -> 127.0.0.1:3081
*.apps.example.com -> 127.0.0.1:8088
```
DNS：
- `portal.example.com` -> 服务器 IP
- `apps.example.com` -> 服务器 IP
- `*.apps.example.com` -> 服务器 IP
公网代理：
- `portal.example.com` -> `127.0.0.1:3081`
- `*.apps.example.com` -> `127.0.0.1:8088`
---
## 8. 一个常见误区
### 误区 1
“我把 `portal.example.com` 配给 `8088` 可以吗？”
技术上能转，但不推荐。
因为：
- `8088` 是实例入口
- `3081` 才是门户入口
更清晰的职责划分应该是：
- 门户 -> `3081`
- 实例 -> `8088`
### 误区 2
“我能不能把 `8090` 和 `19090` 也直接开放给公网？”
不建议。
因为：
- `8090` 是内部部署控制面
- `19090` 是内部鉴权服务
这两个应该尽量只允许容器网络或内网访问。
### 误区 3
“DNS 能不能直接决定端口？”
不能。
DNS 只能决定：
- 域名 -> IP
端口是：
- 浏览器默认端口规则
- URL 里显式写端口
- 反向代理转发规则
共同决定的。
---
## 9. 最简单的理解方式
把它拆成两件事就不容易乱：
### 系统内的事
这个项目要知道：
- 实例公网地址长什么样
- 新实例生成什么域名
- 对外协议是 `http` 还是 `https`
所以它关心：
- `DEPLOY_PUBLIC_SCHEME`
- `DEPLOY_PUBLIC_BASE_DOMAIN`
- `DEPLOY_PUBLIC_PORT`
### 系统外的事
你的服务器或云环境要负责：
- 域名解析
- TLS 证书
- 80/443 入口
- 把请求转给 `3081` 或 `8088`
---
## 10. 如果你现在只是本机测试
那你可以完全先不管正式域名。
继续用：
```bash
export NANO_BASE_DOMAIN=127.0.0.1.nip.io
```text
portal.example.com -> 服务器 IP
apps.example.com -> 服务器 IP
*.apps.example.com -> 服务器 IP
```
这已经足够验证整个系统：
## 8. Nginx 外层代理示例
示例只展示关键转发逻辑，证书路径和自动签发方式按你的环境调整。
```nginx
server {
listen 80;
server_name portal.example.com *.apps.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name portal.example.com;
ssl_certificate /etc/letsencrypt/live/portal.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/portal.example.com/privkey.pem;
location / {
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;
proxy_pass http://127.0.0.1:3081;
}
}
server {
listen 443 ssl http2;
server_name *.apps.example.com;
ssl_certificate /etc/letsencrypt/live/apps.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/apps.example.com/privkey.pem;
location / {
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;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_pass http://127.0.0.1:8088;
}
}
```
证书注意：
- `portal.example.com` 可以用普通单域名证书。
- `*.apps.example.com` 需要通配符证书，通常要用 DNS-01 验证。
- 也可以用支持自动证书的 Caddy / Traefik 简化这层。
## 9. 常见误区
### DNS 不能配置端口
DNS 只能做：
```text
域名 -> IP
```
端口来自：
- URL 里显式端口
- 协议默认端口
- 外层代理监听和转发规则
### 不要把 portal 转到 8088
`8088` 是实例入口，不是认证门户入口。
推荐：
```text
portal.example.com -> 3081
*.apps.example.com -> 8088
```
### 不要公开 8090 和 19090
`8090` 是部署控制面，`19090` 是内部 AuthZ 服务。它们应该只允许容器网络或可信内网访问。
### 修改 DEPLOY_PUBLIC_* 后旧实例不会自动改 URL
这些变量影响新创建实例的 `public_url` 和 `instance_host`。旧实例已经写入注册表，需要重新创建或手动更新注册表和代理配置。
## 10. 本机测试不需要正式域名
如果只是本机验证完整链路，继续使用：
```bash
export BEAVER_BASE_DOMAIN=127.0.0.1.nip.io
```
它已经足够测试：
- 注册
- 登录
- 创建实例
- 自动创建实例
- 跳转个人实例
等你准备真正对外给别人访问时，再处理正式域名和 HTTPS。
---
## 11. 一句话结论
如果你问：
“域名应该配到什么端口上？”
最实用的答案是：
- 门户域名 -> `3081`
- 实例泛域名 -> `8088`
- `8090` 和 `19090` 不建议直接公开
但更准确地说：
- 域名解析本身不带端口
- 真正的端口转发，是由外层反向代理做的
---
## 12. 你后面最可能要补的东西
如果你准备上正式域名，下一步通常是补下面其中一个：
- `Nginx` 反向代理配置
- `Caddy` 配置
- 云负载均衡转发规则
- HTTPS 证书配置
如果你要，我下一步可以继续给你补：
- `Nginx 域名反代示例.md`
- 或者 `Caddy 域名反代示例.md`
都可以直接按这个项目的端口结构来写。
等准备对外访问时，再切换正式 DNS、HTTPS 和外层代理。