143 lines
4.0 KiB
Markdown
143 lines
4.0 KiB
Markdown
# 域名与 HTTPS
|
||
|
||
## 默认路径：company-deploy-mcp（优先）
|
||
|
||
业务部署 **不要** 手写 Dokploy `domain.create`。
|
||
控制面在 `apply_deployment_plan` 内自动绑定域名并启用 HTTPS。
|
||
|
||
### 主机名规则
|
||
|
||
| 项 | 值 |
|
||
|----|-----|
|
||
| 格式 | `{prefix}{random}.{DOMAIN_ROOT}` |
|
||
| 默认 prefix | `buxi` |
|
||
| 默认 random | 5 位 `[a-z0-9]` |
|
||
| 默认根域 | `loncode.site`（以控制面 `DOMAIN_ROOT` 为准） |
|
||
| 示例 | `buxi3k9xa.loncode.site` |
|
||
|
||
- **首次** `apply` 且 `exposeWeb !== false` 时分配
|
||
- 分配后写入项目 mapping，**同 repo+environment 永久复用**
|
||
- 可用 `spec.domainHost` 指定固定 host（需 DNS 已解析到 Dokploy；一般业务勿用）
|
||
- `exposeWeb: false`：不绑公网域（Worker / 长连接机器人）
|
||
|
||
### HTTPS / 证书
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| 默认 | `DOMAIN_HTTPS=true`，`certificateType=letsencrypt` |
|
||
| 实现 | Dokploy Traefik 按**具体子域**申请 Let’s Encrypt |
|
||
| **不需要** | 通配符证书（`*.loncode.site` 的 cert） |
|
||
| **需要** | DNS 把子域指到 Dokploy；**80/443** 公网可达（HTTP-01） |
|
||
|
||
推荐 DNS（一次配好，所有项目共用）：
|
||
|
||
```text
|
||
*.loncode.site → A/AAAA → Dokploy 服务器 IP
|
||
```
|
||
|
||
这是通配 **解析**，不是通配证书。每个 `buxi*****.loncode.site` 各自签 LE。
|
||
|
||
### 交付链接
|
||
|
||
| 来源 | 字段 |
|
||
|------|------|
|
||
| `apply_deployment_plan` | `url`、`domain.host`、`domain.url` |
|
||
| `list_projects` | 每项 `url` / `domainHost` |
|
||
| `get_deployment_status` | 结合应用状态与 mapping |
|
||
|
||
格式：`https://<host>/`（控制面 `DOMAIN_HTTPS=false` 时才是 `http://`）。
|
||
|
||
Agent 探活：
|
||
|
||
```bash
|
||
curl -skI "https://buxiXXXXX.loncode.site/"
|
||
# 或健康路径
|
||
curl -skI "https://buxiXXXXX.loncode.site/healthz"
|
||
```
|
||
|
||
首次可能短暂 404 / TLS 握手失败：等 1–3 分钟 LE；仍失败查 DNS 与 80/443。
|
||
|
||
### Agent 红线（MCP 路径）
|
||
|
||
1. **不要**再调 Dokploy `domain.create`（双绑/冲突）
|
||
2. **不要**要求业务用户填 `DOKPLOY_DOMAIN`
|
||
3. **不要**把错误的宿主机端口（如别人的 `:8080`）当成产品链接
|
||
4. 证书失败：查基础设施，不要改业务代码「硬编码域名」进 Git
|
||
|
||
细节与 plan 参数见 `mcp-deploy.md`。
|
||
|
||
---
|
||
|
||
## Legacy 路径：直连 Dokploy（运维例外）
|
||
|
||
仅当用户明确要求不走 MCP，且存在项目 `.env.deploy` 时使用。
|
||
|
||
### 配置写在哪？
|
||
|
||
| 位置 | 用途 |
|
||
|------|------|
|
||
| **项目根 `.env.deploy`** | Agent 读取；必须 gitignore |
|
||
| `env-deploy.example` | 模板 |
|
||
| Dokploy 面板 Domains | 人工补绑 |
|
||
| 域名注册商 DNS | 用户/运维配置 |
|
||
|
||
### 方式 A：写死完整域名
|
||
|
||
```bash
|
||
DOKPLOY_EXPOSE_WEB=true
|
||
DOKPLOY_DOMAIN=crm.loncode.site
|
||
DOKPLOY_DOMAIN_HTTPS=true
|
||
DOKPLOY_DNS_READY=true
|
||
DOKPLOY_PORT=3000
|
||
```
|
||
|
||
### 方式 B：根域 + slug
|
||
|
||
```bash
|
||
DOKPLOY_EXPOSE_WEB=true
|
||
DOKPLOY_DOMAIN_ROOT=loncode.site
|
||
DOKPLOY_DOMAIN_PREFIX=
|
||
# DOKPLOY_DOMAIN 留空 → {PREFIX}{slug}.{ROOT}
|
||
```
|
||
|
||
与控制面 `buxi+5` 规则**不同**（legacy 多为 app 名 slug）。
|
||
企业统一对外仍推荐 **MCP 的 buxi+5**，避免与连接中心体验分裂。
|
||
|
||
### 方式 C：非 Web
|
||
|
||
```bash
|
||
DOKPLOY_EXPOSE_WEB=false
|
||
```
|
||
|
||
### Legacy API 示例
|
||
|
||
```bash
|
||
curl -sS -X POST \
|
||
-H "x-api-key: $DOKPLOY_API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d "{
|
||
\"host\": \"${DOKPLOY_DOMAIN}\",
|
||
\"applicationId\": \"${DOKPLOY_APPLICATION_ID}\",
|
||
\"https\": true,
|
||
\"certificateType\": \"letsencrypt\",
|
||
\"port\": ${DOKPLOY_PORT},
|
||
\"path\": \"/\",
|
||
\"domainType\": \"application\"
|
||
}" \
|
||
"${DOKPLOY_URL}/api/domain.create"
|
||
```
|
||
|
||
`host` **不要**带协议。证书同样依赖 DNS + 80/443。
|
||
|
||
---
|
||
|
||
## 故障速查
|
||
|
||
| 现象 | 处理 |
|
||
|------|------|
|
||
| 有 host 无 HTTPS | 等 LE；查 80 是否被占用/防火墙 |
|
||
| DNS NXDOMAIN | 配 `*.DOMAIN_ROOT` 或单条 A 记录 |
|
||
| 证书反复失败 | 确认公网能访问该 host 的 80 |
|
||
| 打开了错误站点 | 是否绑到了别的 applicationId |
|
||
| MCP 与 legacy 双绑 | 停掉一侧；优先只走 MCP |
|