steven_li
9d6cde2d23
- 将所有环境变量前缀从NANO_改为BEAVER_ - 更新README.md文档内容，包括项目介绍、组件说明和快速开始指南 - 修改.gitignore文件，添加auth-portal运行时路径排除规则 - 更新app-instance镜像标签从nano/app-instance改为beaver/app-instance - 增强技能安全检查器，支持工具前缀白名单功能 - 添加技能草稿重新检查安全性API端点 - 扩展证据选择器，收集工具调用名称用于技能学习 - 改进技能合成器，基于实际调用的工具生成工具提示 - 优化路由超时处理机制，增加重试逻辑 - 更新后端架构文档，添加可视化入口和基础概念说明 - 实现在WebSocket消息中传递工具迭代次数信息
336 lines
7.6 KiB
Markdown
336 lines
7.6 KiB
Markdown
# Beaver Project 域名配置指引
|
||
|
||
这份文档说明如何从本机测试域名 `127.0.0.1.nip.io` 切换到正式域名。
|
||
|
||
核心结论：
|
||
|
||
- DNS 只负责把域名解析到 IP。
|
||
- DNS 不负责端口。
|
||
- `auth-portal` 和用户实例建议使用不同域名。
|
||
- 正式环境建议用外层 Nginx、Caddy、Traefik 或云负载均衡监听 `80/443`。
|
||
- `router-proxy` 必须收到原始 `Host` 头，才能按实例域名转发。
|
||
|
||
## 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. 推荐域名规划
|
||
|
||
推荐拆成两个域名空间：
|
||
|
||
```text
|
||
https://portal.example.com
|
||
https://alice.apps.example.com
|
||
https://bob.apps.example.com
|
||
```
|
||
|
||
含义：
|
||
|
||
- `portal.example.com` 给 `auth-portal`
|
||
- `*.apps.example.com` 给 `router-proxy`
|
||
- 每个实例使用一个子域名，例如 `alice.apps.example.com`
|
||
|
||
不要把门户和实例混在同一个 Host 上。`router-proxy` 是实例入口，`auth-portal` 是认证入口，两者职责不同。
|
||
|
||
## 3. DNS 要怎么配
|
||
|
||
假设服务器公网 IP 是 `203.0.113.10`。
|
||
|
||
DNS 记录：
|
||
|
||
```text
|
||
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。
|
||
|
||
注意：
|
||
|
||
- `*.apps.example.com` 用于实例子域名。
|
||
- `apps.example.com` 本身不是必须给用户访问，但建议也解析到同一入口，方便证书和排查。
|
||
- DNS 不会决定 `3081`、`8088`、`443` 这些端口。
|
||
|
||
## 4. 外层反向代理要做什么
|
||
|
||
外层代理负责：
|
||
|
||
- 监听公网 `80/443`
|
||
- 处理 TLS 证书
|
||
- 按 Host 转发请求
|
||
- 透传原始 Host
|
||
- 支持 WebSocket upgrade
|
||
|
||
最小映射：
|
||
|
||
```text
|
||
portal.example.com -> http://127.0.0.1:3081
|
||
*.apps.example.com -> http://127.0.0.1:8088
|
||
```
|
||
|
||
`*.apps.example.com` 转发到 `router-proxy` 时必须保留原始 Host，例如：
|
||
|
||
```nginx
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Forwarded-Host $host;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
```
|
||
|
||
否则 `router-proxy` 无法知道请求属于哪个实例。
|
||
|
||
## 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
|
||
export BEAVER_BASE_DOMAIN=127.0.0.1.nip.io
|
||
```
|
||
|
||
`deploy-control`：
|
||
|
||
```bash
|
||
-e DEPLOY_PUBLIC_SCHEME="http" \
|
||
-e DEPLOY_PUBLIC_BASE_DOMAIN="$BEAVER_BASE_DOMAIN" \
|
||
-e DEPLOY_PUBLIC_PORT="8088" \
|
||
```
|
||
|
||
生成实例地址：
|
||
|
||
```text
|
||
http://alice.127.0.0.1.nip.io:8088
|
||
```
|
||
|
||
正式 HTTPS：
|
||
|
||
```bash
|
||
export BEAVER_BASE_DOMAIN=apps.example.com
|
||
```
|
||
|
||
`deploy-control`：
|
||
|
||
```bash
|
||
-e DEPLOY_PUBLIC_SCHEME="https" \
|
||
-e DEPLOY_PUBLIC_BASE_DOMAIN="apps.example.com" \
|
||
-e DEPLOY_PUBLIC_PORT="443" \
|
||
```
|
||
|
||
生成实例地址：
|
||
|
||
```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：
|
||
|
||
```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
|
||
```
|
||
|
||
它已经足够测试：
|
||
|
||
- 注册
|
||
- 登录
|
||
- 自动创建实例
|
||
- 跳转个人实例
|
||
|
||
等准备对外访问时，再切换正式 DNS、HTTPS 和外层代理。
|