# nano_project 域名配置指引

这份文档专门解释一件事：

- 如果你不用 `127.0.0.1.nip.io`
- 想换成自己的正式域名
- 应该怎么理解、怎么配、该改哪些地方

先说最重要的结论：

- `DNS` 只管把域名解析到 `IP`
- `端口` 不归 DNS 管
- 所以“域名配到哪个端口”本质上是反向代理或公网入口层在处理

也就是说：

- 域名解析本身，是项目外部的事情
- 但项目里生成出来的实例地址、门户地址，又会依赖你填的域名

所以这件事是：

- 一半在系统外
- 一半和系统配置有关

---

## 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
https://alice.apps.example.com
https://bob.apps.example.com
```

其中：

- `portal.example.com` 走 `auth-portal`
- `alice.apps.example.com` 走 `router-proxy`

---

## 3. 只配 DNS 还不够

很多人最容易误解的是：

“我把域名解析到服务器 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`

也就是：

```text
portal.example.com  -> auth-portal   -> 3081
*.apps.example.com  -> router-proxy  -> 8088
```

注意：

- `router-proxy` 是靠 `Host` 头识别具体实例的
- 所以必须把原始 Host 透传过去

---

## 5. 这个项目内部哪些值要改

如果你要从 `127.0.0.1.nip.io` 换成正式域名，至少要改这些：

### 本机部署变量里

把：

```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
```

如果你后面还有外层 `80/443` 代理，不想让用户看到 `:8088`，那还需要额外调整入口层做无端口访问转发。

### `deploy-control` 里实际影响实例地址的变量

它们是：

- `DEPLOY_PUBLIC_SCHEME`
- `DEPLOY_PUBLIC_BASE_DOMAIN`
- `DEPLOY_PUBLIC_PORT`

例如：

```bash
-e DEPLOY_PUBLIC_SCHEME="https" \
-e DEPLOY_PUBLIC_BASE_DOMAIN="apps.example.com" \
-e DEPLOY_PUBLIC_PORT="443" \
```

或者如果你暂时还是明文 HTTP：

```bash
-e DEPLOY_PUBLIC_SCHEME="http" \
-e DEPLOY_PUBLIC_BASE_DOMAIN="apps.example.com" \
-e DEPLOY_PUBLIC_PORT="8088" \
```

---

## 6. 什么时候可以把端口从 URL 里去掉

如果你希望用户访问：

```text
https://alice.apps.example.com
```

而不是：

```text
http://alice.apps.example.com:8088
```

那你需要满足这两个条件：

1. 外层已经有监听 `80/443` 的反向代理
2. 它已经把 `*.apps.example.com` 转发到本机 `8088`

这时项目内部就应该写：

```bash
DEPLOY_PUBLIC_SCHEME=https
DEPLOY_PUBLIC_BASE_DOMAIN=apps.example.com
DEPLOY_PUBLIC_PORT=443
```

或者很多时候你也可以直接在显示层隐藏默认端口概念，让用户只看标准 `https` 地址。

---

## 7. 一套推荐的正式域名方案

假设你有：

- 门户域名：`portal.example.com`
- 实例根域名：`apps.example.com`

推荐这样做：

### 项目内部

`deploy-control`：

```bash
-e DEPLOY_PUBLIC_SCHEME="https" \
-e DEPLOY_PUBLIC_BASE_DOMAIN="apps.example.com" \
-e DEPLOY_PUBLIC_PORT="443" \
```

本机部署变量：

```bash
export NANO_BASE_DOMAIN=apps.example.com
```

### 项目外部

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
```

这已经足够验证整个系统：

- 注册
- 登录
- 创建实例
- 跳转个人实例

等你准备真正对外给别人访问时，再处理正式域名和 HTTPS。

---

## 11. 一句话结论

如果你问：

“域名应该配到什么端口上？”

最实用的答案是：

- 门户域名 -> `3081`
- 实例泛域名 -> `8088`
- `8090` 和 `19090` 不建议直接公开

但更准确地说：

- 域名解析本身不带端口
- 真正的端口转发，是由外层反向代理做的

---

## 12. 你后面最可能要补的东西

如果你准备上正式域名，下一步通常是补下面其中一个：

- `Nginx` 反向代理配置
- `Caddy` 配置
- 云负载均衡转发规则
- HTTPS 证书配置

如果你要，我下一步可以继续给你补：

- `Nginx 域名反代示例.md`
- 或者 `Caddy 域名反代示例.md`

都可以直接按这个项目的端口结构来写。
