# Mở nhiều URL cho một project (URL phụ)

Skill cha: [tdshift-paas](https://app.tdshift.info/skill) · Cần: project loại `compose` ở trạng thái `ready`, Compose đã qua quy tắc trong [deploy-compose](https://app.tdshift.info/skill/deploy-compose.md)

Mỗi project Compose có **một URL chính** (ô **Public web service** + **Internal HTTP port**, dùng cho health check và domain riêng) và tối đa **10 URL phụ**. Mỗi URL phụ mở một cổng HTTP của một service trong cùng Compose, ví dụ Odoo ở URL chính, pgAdmin và Mailpit ở URL phụ.

## Địa chỉ được tạo

URL phụ tên `<tên>` có địa chỉ **`https://<mã project>-<tên>.<domain project>`** (một cấp, nối bằng dấu gạch ngang). Ví dụ project `project-ac8580a192`:

| Dòng URL phụ | Địa chỉ | Trỏ tới |
|---|---|---|
| (URL chính) | `https://project-ac8580a192.tdshift.info` | `odoo:8069` |
| `db=pgadmin:80` | `https://project-ac8580a192-db.tdshift.info` | `pgadmin:80` |
| `ws=odoo:8072` | `https://project-ac8580a192-ws.tdshift.info` | `odoo:8072` |

Chế độ local: `https://<mã project>-<tên>.localhost:5050`.

**Không** có dạng `db.project-ac8580a192.tdshift.info` (hai cấp): chứng chỉ của proxy Cloudflare chỉ phủ một cấp, trình duyệt sẽ báo lỗi TLS. Không hứa với người dùng dạng địa chỉ này.

## Quy tắc

- `tên`: 1–20 ký tự `a-z`, `0-9`, `-`; không bắt đầu/kết thúc bằng `-`; không trùng nhau trong project. Chữ hoa nhập trên giao diện được đổi thành chữ thường.
- `service`: tên service có trong Compose của chính project. Một service được mở nhiều cổng (nhiều dòng).
- `cổng`: cổng HTTP mà service lắng nghe **bên trong container** (1–65535), không phải cổng host. Không khai `ports:` trong Compose.
- Chỉ HTTP/HTTPS qua Traefik. Cổng TCP thô (PostgreSQL 5432, Redis, MySQL…) **không** mở được bằng URL phụ; PostgreSQL xem mục TCP/TLS trong [domain-rieng](https://app.tdshift.info/skill/domain-rieng.md).
- Không định tuyến theo đường dẫn (`/pgadmin`); mỗi URL phụ là một hostname riêng.
- Health check chỉ kiểm tra URL chính. URL phụ lỗi không làm deploy thất bại.
- Domain riêng chỉ gắn cho URL chính; URL phụ luôn dùng địa chỉ tự sinh.
- URL phụ **công khai trên Internet, không có lớp đăng nhập của PaaS**. Chỉ mở service có đăng nhập riêng (pgAdmin, Odoo, Grafana…), đặt mật khẩu mạnh qua biến môi trường. Không mở service quản trị không có mật khẩu.

## Trên giao diện

Trang project → **Docker Compose Editor**:

1. Điền Compose, **Public web service**, **Internal HTTP port**, **Health path** như bình thường.
2. Ô **URL phụ (tùy chọn)**: mỗi dòng `tên=service:cổng`, ví dụ:
   ```
   db=pgadmin:80
   ws=odoo:8072
   ```
   Dòng trống và dòng bắt đầu bằng `#` bị bỏ qua.
3. Bấm **Deploy Compose Stack ↗**. Thêm, sửa, xoá URL phụ đều **chỉ có hiệu lực sau khi deploy**.
4. Sau khi trạng thái về `ready`, khu **Domains & Routing** liệt kê từng URL phụ (bấm để mở) kèm `service:cổng`.

Xoá hết URL phụ: để trống ô **URL phụ (tùy chọn)** rồi deploy lại.

## Qua Agent API

`PUT /api/v1/agent/projects/<UUID>/compose` nhận thêm `extra_routes`:

```json
{"compose":"<YAML>","web_service":"odoo","port":8069,"health_path":"/web/login",
 "extra_routes":[{"name":"db","service":"pgadmin","port":80},{"name":"ws","service":"odoo","port":8072}]}
```

- Không gửi `extra_routes` → **giữ** danh sách đã lưu. Gửi `[]` → xoá hết.
- Sai quy tắc → `422 {"error":"Invalid Compose: URL phụ db: không có service \"pgadmin\" trong Compose."}`. `extra_routes` không phải danh sách (ví dụ chuỗi) → 422.
- `GET .../configuration` trả `extra_routes` của bản nháp.
- Sau deploy, `GET /api/v1/agent/projects/<UUID>` trả `url` (URL chính) và `extra_routes` đang chạy, mỗi mục có `url`.
- `POST .../deploy`, `PUT .../image` và Deployment API `POST /api/v1/projects/<UUID>/deploy` dùng lại đúng `extra_routes` đã lưu.

## Quy trình bắt buộc cho AI

1. Đọc Compose hiện tại (`GET .../configuration` hoặc trang project); lấy tên service và cổng **từ Compose/tài liệu image**, không đoán (pgAdmin `dpage/pgadmin4` lắng nghe 80, Odoo 8069 và 8072 cho websocket, Mailpit 8025).
2. Hỏi người dùng tên ngắn cho từng URL phụ nếu họ chưa nêu; nhắc rằng URL phụ công khai.
3. Lưu bằng `PUT .../compose` kèm `extra_routes` (hoặc hướng dẫn người dùng điền ô **URL phụ (tùy chọn)**).
4. Chỉ deploy khi người dùng muốn (`POST .../deploy`), chờ `GET .../<UUID>` về `ready` với `error: null`.
5. Báo địa chỉ lấy từ trường `extra_routes[].url` trả về, không tự ghép. Lần đầu mở có thể mất vài giây để cấp chứng chỉ.

## Lỗi thường gặp

| Dấu hiệu | Nguyên nhân | Cách xử lý |
|---|---|---|
| `URL phụ: mỗi dòng dạng tên=service:cổng…` | Sai định dạng dòng | Viết `db=pgadmin:80` |
| `Tên URL phụ dài 1–20 ký tự…` | Tên có ký tự lạ, `_`, hoặc quá dài | Đổi tên ngắn chỉ gồm a-z, 0-9, `-` |
| `URL phụ db: không có service "…" trong Compose.` | Sai tên service | Dùng đúng tên trong `services:` |
| `Tên URL phụ "db" bị trùng.` | Hai dòng cùng tên | Đổi tên một dòng |
| `URL phụ …: tên miền trùng địa chỉ của project khác.` | Địa chỉ ghép ra trùng project cũ | Chọn tên khác |
| Mở URL phụ báo 502/Bad Gateway | Cổng sai hoặc service chưa chạy | Kiểm tra cổng nội bộ và **Logs theo service** |
| Lỗi TLS khi mở `db.<project>…` | Dùng dạng hai cấp | Dùng `<project>-db…` |

Hướng dẫn đầy đủ cho người: `docs/NHIEU_URL.md` trong repo portal.
