167 lines
8.4 KiB
Markdown
167 lines
8.4 KiB
Markdown
---
|
||
title: 为新服务配置 LAN HTTPS 入口
|
||
lifecycle: active
|
||
evidence: documented
|
||
last_reviewed: 2026-09-16
|
||
last_verified: null
|
||
---
|
||
|
||
# 为新服务配置 LAN HTTPS 入口
|
||
|
||
普通 LAN Web 服务使用 `your-app.ad.ddupan.top`，复用共享 Envoy Gateway 和通配符证书。
|
||
本指南串联应用 Service、路由、DNS、认证与 GitOps；示例不会自动创建任何对象。
|
||
本轮只读仓库与上游资料，未查询现场、签发证书或发布服务。
|
||
|
||
## 接入前明确应用参数
|
||
|
||
准备应用 namespace、Service 名称与 **Service port**、域名、访问人群及认证方式。
|
||
先让应用及其 Service 在集群内可用；需要秘密或持久存储时，分别参考
|
||
[External Secrets](../services/external-secrets.md) 和 [OpenEBS](../services/openebs.md)。
|
||
|
||
本例约定 namespace 和 Service 均为 `your-app`，Service port 为 `8080`。
|
||
这些都是占位值，须替换为实际配置。HTTPRoute 不负责部署应用、创建 namespace 或授予应用权限。
|
||
|
||
## 1. 复用现有证书与 listener
|
||
|
||
共享入口为 `envoy-gateway-system/eg`，普通 LAN 域名绑定 `https` listener。
|
||
其证书 Secret 为 `envoy-gateway-system/wildcard-ad-ddupan-top-tls`，由 cert-manager 管理。
|
||
|
||
| 域名场景 | 接入选择 |
|
||
|---|---|
|
||
| `your-app.ad.ddupan.top` | 复用 `https` listener 与通配符证书 |
|
||
| `auth.ddupan.top`、`git.ddupan.top` | 已有各自的 `https-auth`、`https-git` listener |
|
||
| 更深的域名或其他域 | 单独设计证书 SAN 与匹配的 listener，不能套用本例 |
|
||
|
||
TLS 通配符只覆盖一层子域。证书包含 `ad.ddupan.top` SAN 也不表示现有 listener 会接收这个 apex；
|
||
证书名称和 listener hostname 是两个需要同时满足的条件。
|
||
新 LAN 服务不需要复制私钥、创建第二个 Gateway 或重新安装 cert-manager。
|
||
|
||
现有通配符通过 `ClusterIssuer/letsencrypt` 与 Cloudflare DNS-01 签发。
|
||
DNS-01 不要求业务端口对公网开放；自检需保留现有公共递归 resolver 设置，避免内部 AD 视图看不到公开 TXT。
|
||
详见 [cert-manager DNS-01](https://cert-manager.io/docs/configuration/acme/dns01/)。
|
||
`bao-acme` 是内部 CA 的另一个选择，客户端需信任内部 CA；它不是无需配套调整的通配符替代品。
|
||
|
||
## 2. 在应用 namespace 声明 HTTPRoute
|
||
|
||
```yaml
|
||
apiVersion: gateway.networking.k8s.io/v1
|
||
kind: HTTPRoute
|
||
metadata:
|
||
name: your-app
|
||
namespace: your-app
|
||
spec:
|
||
parentRefs:
|
||
- name: eg
|
||
namespace: envoy-gateway-system
|
||
sectionName: https
|
||
hostnames:
|
||
- your-app.ad.ddupan.top
|
||
rules:
|
||
- matches:
|
||
- path:
|
||
type: PathPrefix
|
||
value: /
|
||
backendRefs:
|
||
- name: your-app
|
||
port: 8080
|
||
```
|
||
|
||
本例后端 Service 与路由同 namespace；`8080` 必须是 Service 暴露的端口，不直接照搬容器端口。
|
||
跨 namespace 后端引用还需目标 namespace 的 ReferenceGrant，不能只增加一个 namespace 字段就认为授权完成。
|
||
共享 Gateway 的 `allowedRoutes` 允许其他 namespace 挂载路由，但这不等于应用已经得到用户认证保护。
|
||
|
||
需要 HTTP→HTTPS 跳转时，为同一 hostname 增加独立 HTTPRoute，绑定 `sectionName: http`，
|
||
使用 `RequestRedirect` 的 `scheme: https`、`port: 443` 和适当状态码，不配置业务 backend。
|
||
HTTPS 路由本身不会自动生成跳转。规则语义参考
|
||
[Gateway API 跳转指南](https://gateway-api.sigs.k8s.io/guides/user-guides/http-redirect-rewrite/)。
|
||
保留 HTTP listener 的 ACME 用途，不为单个应用替换整个 listener。
|
||
|
||
## 3. 在受管 DNS 清单增加名称
|
||
|
||
工作区的声明入口为 `infrastructure/dns/records.yml`，在 `homelab_dns.samba.records`
|
||
现有列表中增加以下 RRset，不能用这个片段覆盖原列表：
|
||
|
||
```yaml
|
||
- zone: ad.ddupan.top
|
||
name: your-app
|
||
type: A
|
||
values:
|
||
- 192.168.10.127
|
||
```
|
||
|
||
该地址来自共享 Envoy Gateway 的现有记录。Samba Ansible 的 `provision-dc.yml` 已引用该清单，
|
||
DNS task 消费 `homelab_dns.samba.records`；旧 README 中增加 `samba_ad_extra_a_records` 的步骤不再作为本页入口。
|
||
相关 DNS 清单与任务存在工作区改动，正式合并来源仍需补全，不能认定任意远端 checkout 都已包含它们。
|
||
|
||
维护者先审查针对 DNS 的 Ansible check/diff，再按既有流程应用。受管 RRset 的 exact 语义可能移除同名同类型的其他值，
|
||
因此应检查完整记录集合；不要遍历清理 Samba 自动生成的 AD/Kerberos 记录。
|
||
|
||
[LAN DNS](../services/lan-dns.md) 与 [Pod DNS](../services/k3s-dns.md) 的路径不同，
|
||
新增名称后分别检查所需视图。LAN 已使用 Blocky，不采用旧 DNS README 中“尚未成为正式 resolver”的历史表述。
|
||
|
||
## 4. 按应用选择认证
|
||
|
||
| 应用类型 | 接入方式 |
|
||
|---|---|
|
||
| 已支持 OIDC 的 Web 应用 | 按应用文档接入 Authelia，配置 client、回调地址与应用内权限 |
|
||
| 信任反向代理身份头的应用 | 配套 Envoy SecurityPolicy、Authelia 规则及阻止绕过网关的网络策略 |
|
||
| API、Git、机器客户端 | 使用服务支持的认证协议，避免浏览器登录跳转截获协议请求 |
|
||
|
||
Gitea 使用原生登录/OIDC 和 Git token，因此其路由没有套用 NetBox 的 forward-auth。
|
||
SPIFFE workload 接入按[机器身份原则](../services/spire.md)设计，服务自行授权；
|
||
HTTPS 证书和 HTTPRoute 都不会自动替代业务认证。
|
||
|
||
forward-auth 的现有参考为 `apps/netbox/securitypolicy.yaml` 与 `networkpolicy.yaml`，另需协调：
|
||
|
||
- `apps/authelia/referencegrant-extauth.yaml`：目标 namespace 授权新的 SecurityPolicy 来源。
|
||
- `apps/authelia/values.yaml`：目标域名及访问群组规则。
|
||
- 应用配置：信任哪些身份头，以及如何映射用户权限。
|
||
|
||
复制前逐项替换 route 名、namespace、Pod selector 和端口。现有 Authelia Service port 是 `80`，
|
||
不是容器 `9091`；`headersToBackend` 位于 `extAuth.http`，并由可信结果覆盖客户端同名头。
|
||
保留 `failOpen: false`，同时限制直接访问后端的路径。NetworkPolicy 的 probe 例外与节点地址需按应用核对，
|
||
不能机械复制 NetBox 的节点白名单。
|
||
|
||
## 5. 纳入部署入口并验收
|
||
|
||
将路由和配套策略加入应用 Kustomization 或 chart values，并确认应用由哪个 Flux Kustomization 管理。
|
||
只新建 YAML 文件不会使它自动部署。独立新应用还需 namespace 与集群 reconciliation 入口，
|
||
按 `clusters/homelab/README.md` 审查；不要为接入一个应用开启全局 prune。
|
||
|
||
先本地渲染并检查 diff，合并后由已有 GitOps 流程交付。获得现场检查授权后，分层验证：
|
||
|
||
1. Flux 已同步目标 revision；后端 Service 有可用 endpoint。
|
||
2. Gateway listener 可用，HTTPRoute 对目标 parent 的 `Accepted`、`ResolvedRefs` 为 True。
|
||
3. 从相应客户端解析新名称，并检查证书名称与信任链。
|
||
4. 验证登录、应用权限及需要支持的 API/机器客户端，不能只检查首页 200。
|
||
|
||
若需分开验证入口与 DNS，可在已授权的客户端使用以下诊断请求，域名仍保留在 TLS SNI 与 Host 中：
|
||
|
||
```bash
|
||
curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' \
|
||
--resolve your-app.ad.ddupan.top:443:192.168.10.127 \
|
||
https://your-app.ad.ddupan.top/
|
||
```
|
||
|
||
该命令绕过客户端 DNS，不是 DNS 验收；不加 `-k` 绕过证书校验。
|
||
响应是否符合预期取决于应用，受保护页面可能返回登录跳转。
|
||
|
||
## LAN 入口与公网发布的边界
|
||
|
||
本指南只完成 LAN HTTPS 路径。公开可信证书不意味着服务已开放公网。
|
||
公网发布还需单独审查 Cloudflare DNS、Tunnel 路由、访问控制与应用外部 URL，
|
||
入口为 `infrastructure/cloudflared/terraform/README.md`；不要从已有域名复制 Tunnel 设置就宣称完成发布。
|
||
|
||
## 来源与维护
|
||
|
||
homelab-infra：`platform/cert-manager/README.md`、`certificate-wildcard-ad.yaml`，
|
||
`platform/envoy-gateway/README.md`、`gateway.yaml`，`infrastructure/dns/`，
|
||
`infrastructure/samba-ad/ansible/`，`apps/netbox/`，`apps/authelia/referencegrant-extauth.yaml`，
|
||
`apps/gitea/httproute.yaml` 与 `clusters/homelab/README.md`。
|
||
|
||
`apps/http-echo/httproute.yaml` 是已排除出 Kustomization 的历史 Contour 示例，
|
||
`archive/traefik/` 也不是当前接入模板；不要因文件存在就直接应用。
|
||
上述源码 README 的旧描述尚待同步，本页按实际所读配置与维护者已经确认的结论整理。
|
||
|
||
来源文件的固定版本与工作区差异见[来源追溯](../sources.md#publish-service)。
|