# 域名与 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 |