labweb/docs/strategy-1-path-prefix.md

# 策略 1：路径前缀部署方案

## 📋 策略概述

**核心思想**：使用单一域名，通过 URL 路径前缀区分不同的网站或应用。

**访问方式**：
```
https://amiap.hzau.edu.cn/ABM      # ABM 数据库
https://amiap.hzau.edu.cn/lab      # 实验室主页
https://amiap.hzau.edu.cn/docs     # 文档中心
https://amiap.hzau.edu.cn/         # 主站或 decoy 站点
```

---

## 🏗️ 技术架构

### 路由配置
```yaml
services:
  nginx-abm:
    labels:
      - "traefik.http.routers.abm.rule=Host(`amiap.hzau.edu.cn`) && PathPrefix(`/ABM`)"
      - "traefik.http.routers.abm.priority=100"  # 关键配置！
      
  nginx-lab:
    labels:
      - "traefik.http.routers.lab.rule=Host(`amiap.hzau.edu.cn`) && PathPrefix(`/lab`)"
      - "traefik.http.routers.lab.priority=100"
      
  decoy-site:
    labels:
      - "traefik.http.routers.decoy.rule=Host(`amiap.hzau.edu.cn`) && Path(`/`)"
      - "traefik.http.routers.decoy.priority=1"  # 最低优先级
```

### 文件系统结构
```
容器 1 (ABM):
/usr/share/nginx/html/
└── ABM/                    ← 关键：路径必须对齐
    ├── index.html
    ├── css/
    ├── js/
    └── img/

容器 2 (Lab):
/usr/share/nginx/html/
└── lab/                    ← 路径对齐
    ├── index.html
    └── assets/

容器 3 (Docs):
/usr/share/nginx/html/
└── docs/                   ← 路径对齐
    ├── index.html
    └── static/
```

### 工作流程
```
1. 用户访问: https://amiap.hzau.edu.cn/ABM/
   ↓
2. Traefik 匹配: PathPrefix(/ABM), priority=100
   ↓
3. 转发到容器: GET /ABM/
   ↓
4. Nginx 查找: /usr/share/nginx/html/ABM/index.html
   ↓
5. 返回页面: HTML 中链接 <a href="page.html">
   ↓
6. 浏览器计算: /ABM/ + page.html = /ABM/page.html ✅
```

---

## ✅ 优点分析

### 1. 无需 DNS 配置
- **优势**：适用于没有 DNS 管理权限的场景
- **场景**：学校服务器、共享主机、临时测试环境
- **成本**：零额外配置成本

### 2. 证书管理简单
- **优势**：只需一个域名证书
- **对比**：子域名方案需要通配符证书或多个证书
- **实施**：Let's Encrypt HTTP Challenge 即可

### 3. 部署快速
- **优势**：可以快速启动新项目
- **时间**：5-10 分钟即可部署一个新网站
- **流程**：复制配置模板 → 调整路径 → 启动容器

### 4. 资源节约
- **优势**：共享同一个 SSL 连接和证书
- **性能**：减少 TLS 握手次数
- **带宽**：共享连接池

### 5. 适合小规模部署
- **优势**：网站数量 ≤ 5 个时管理简单
- **维护**：配置文件集中管理
- **可控**：问题排查相对容易

---

## ❌ 缺点分析

### 1. 必须配置优先级（容易出错）
**问题**：
```yaml
# 如果忘记设置 priority
PathPrefix(/ABM)          # priority 默认可能为 0
Path(/)                   # priority 默认可能为 0
# 可能导致路由匹配混乱
```

**后果**：
- CSS/JS 文件加载失败
- 静态资源返回 404
- 页面样式错乱

**解决成本**：每次添加网站都需要仔细检查优先级设置

### 2. 必须调整文件结构
**问题**：
```bash
# 原始网站文件结构
/index.html
/css/style.css
/js/app.js

# 必须调整为
/ABM/index.html
/ABM/css/style.css
/ABM/js/app.js
```

**后果**：
- 需要重新组织文件
- 可能破坏原有构建流程
- 增加部署复杂度

**解决成本**：每个网站都需要手动调整结构

### 3. 不能使用 StripPrefix（或受限使用）
**问题**：
```yaml
# 使用 StripPrefix 会导致路径问题
PathPrefix(/ABM) + StripPrefix(/ABM)
# HTML: <a href="page.html">
# 访问: /page.html ❌ 丢失前缀
```

**限制**：
- 相对路径链接会失效
- 需要修改 HTML 添加 `<base>` 标签
- 或者所有链接改为绝对路径

**解决成本**：修改网站代码或构建流程

### 4. 路由规则复杂度增加
**问题**：
```yaml
# 需要处理的规则越来越多
PathPrefix(/ABM)           priority=100
PathPrefix(/lab)           priority=100
PathPrefix(/docs)          priority=100
PathPrefix(/api)           priority=100
PathPrefix(/downloads)     priority=100
...
Path(/)                    priority=1
```

**后果**：
- 配置文件变得冗长
- 容易遗漏或重复
- 维护成本上升

### 5. 性能稍差
**原因**：
- Traefik 需要匹配多个 PathPrefix 规则
- 路径匹配比域名匹配慢 10-20%
- 多个路由规则增加计算开销

**影响**：
- 高并发下略有影响
- 规则越多越明显
- 对小流量影响不大

### 6. 扩展性受限
**问题**：
- 网站数量增多时，优先级管理变得复杂
- 容易出现优先级冲突
- 调试困难度上升

**临界点**：当网站数量超过 5 个，维护成本指数级上升

### 7. 无法实现完全隔离
**问题**：
- 所有网站共享同一个域名
- 无法为不同网站设置不同的安全策略
- Cookie 作用域可能冲突（同域名）

---

## 🎯 适用场景

### ✅ 最适合的场景

#### 1. 无 DNS 管理权限
```
场景：学校提供的服务器，无法添加子域名
方案：使用路径前缀，无需 DNS 配置
示例：https://server.university.edu.cn/myproject
```

#### 2. 临时项目或测试环境
```
场景：快速搭建演示环境，项目周期短
方案：路径前缀部署快速，无需长期维护
示例：展示给客户的 Demo 网站
```

#### 3. 小规模部署（≤3个网站）
```
场景：个人博客、小团队项目
网站：主站 + 博客 + API 文档
维护：配置简单，管理容易
```

#### 4. 预算受限
```
场景：不想购买多个域名或证书
成本：单域名 + 单证书
适用：个人项目、非盈利项目
```

### ⚠️ 不太适合的场景

#### 1. 生产环境（网站 ≥5个）
- 优先级管理复杂
- 维护成本高
- 易出错

#### 2. 高流量网站
- 性能不是最优
- 路由匹配有额外开销

#### 3. 需要强隔离的多租户系统
- 无法完全隔离
- Cookie 可能冲突
- 安全策略难以分离

#### 4. 长期运行的企业应用
- 扩展性受限
- 不利于未来增长

---

## 📊 性能指标

### 路由匹配性能
```
单次路由匹配时间：0.1-0.5ms
随网站数量线性增长：每增加 1 个网站 +0.05ms
临界点：10 个网站时性能下降明显
```

### 内存占用
```
单个网站额外内存：~5MB（Traefik 路由规则）
10 个网站：~50MB 路由规则内存
```

### CPU 使用
```
路径匹配 CPU 开销：比子域名高 15-20%
高并发场景影响：中等流量下可忽略
```

---

## 🛠️ 最佳实践

### 1. 优先级设置规范
```yaml
# 具体路径：100-200
PathPrefix(/ABM/api)      priority=200
PathPrefix(/ABM)          priority=100

# 通用路径：50
PathPrefix(/static)       priority=50

# 根路径：1
Path(/)                   priority=1
```

### 2. 文件结构标准
```bash
# 严格遵循路径对齐原则
URL: /ABM/page.html
文件: /usr/share/nginx/html/ABM/page.html

# 使用脚本自动化调整
#!/bin/bash
mkdir -p /target/ABM
mv /source/* /target/ABM/
```

### 3. 配置模板化
```yaml
# 创建配置模板
x-website-template: &website-template
  image: nginx:alpine
  networks:
    - frontend
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.SITENAME.entrypoints=web,websecure"
    - "traefik.http.routers.SITENAME.tls.certresolver=myresolver"
    
# 使用模板
nginx-abm:
  <<: *website-template
  volumes:
    - abm-data:/usr/share/nginx/html:ro
  labels:
    - "traefik.http.routers.abm.rule=Host(`amiap.hzau.edu.cn`) && PathPrefix(`/ABM`)"
    - "traefik.http.routers.abm.priority=100"
```

### 4. 监控和日志
```bash
# 定期检查路由匹配
docker logs traefik-reverse | grep "404\|403"

# 验证优先级配置
docker inspect traefik-reverse | jq '.Config.Labels'
```

---

## 💰 成本分析

### 时间成本
```
初次部署：30-60 分钟
添加新网站：10-20 分钟
维护成本：中等（需要管理优先级）
```

### 资源成本
```
域名：1 个（共享）
证书：1 个（Let's Encrypt 免费）
服务器：共享，无额外需求
```

### 学习成本
```
Traefik 基础：中等
优先级规则：需要理解
文件结构调整：简单
总体：中等难度
```

---

## 🔄 迁移路径

### 从路径前缀迁移到子域名

**步骤**：
1. 申请 DNS 记录（保留旧路径）
2. 添加子域名路由规则
3. 调整文件结构（移回根目录）
4. 通知用户新 URL
5. 观察 1-2 周后删除旧路由

**工具**：
```bash
#!/bin/bash
# 迁移脚本
# 从 /ABM/index.html 移回 /index.html
mv /usr/share/nginx/html/ABM/* /usr/share/nginx/html/
rmdir /usr/share/nginx/html/ABM
```

---

## 📝 决策建议

### ✅ 选择此策略的理由

1. **你没有 DNS 管理权限**
2. **项目是临时性的（< 6 个月）**
3. **网站数量少（≤ 3 个）**
4. **快速部署优先于长期维护**
5. **预算有限，不想购买多个域名**

### ❌ 不选择此策略的理由

1. **你有 DNS 管理权限** → 选择策略 2
2. **这是长期运行的生产环境** → 选择策略 2
3. **网站数量会持续增长** → 选择策略 2
4. **追求最佳性能和可维护性** → 选择策略 2

---

## 📚 相关文档

- [完整多站点策略指南](MULTI_SITE_STRATEGY_GUIDE.md)
- [策略 2：子域名方案](strategy-2-subdomain.md)
- [策略 3：混合方案](strategy-3-hybrid.md)
- [总结对比报告](strategy-comparison-report.md)
- [快速参考手册](QUICK_REFERENCE.md)

---

**结论**：路径前缀策略是一个**权宜之计**，适合快速部署和小规模场景，但不是长期最佳方案。如果有条件，建议尽早迁移到子域名策略。