Skip to content

Commit 82a04c3

Browse files
Leechaelclaude
Leechael
and
claude
committed
refactor: restructure namecheap support to use unified DNS provider architecture
- Create NamecheapDNSProvider class implementing DNSProvider interface - Add Namecheap to DNSProviderFactory registration - Update DNS_PROVIDERS.md with Namecheap configuration documentation - Remove old namecheap_dns.py standalone script - Update entrypoint.sh to use unified certman.py and dns_manager.py - Update renew-certificate.sh to use unified certbot manager - Fetch missing certman.py and dns_manager.py from main branch This change integrates Namecheap support into the new unified architecture instead of using standalone scripts, making it consistent with other DNS providers and enabling automatic plugin installation and credential management. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent 91977f1 commit 82a04c3

File tree

13 files changed

+2136
-1
lines changed

13 files changed

+2136
-1
lines changed

‎custom-domain/NAMECHEAP_USAGE.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Namecheap DNS 支持使用指南
2+
3+
这个 nginx 镜像现在支持 Cloudflare 和 Namecheap 两个 DNS 提供商，可以自动申请和更新 SSL 证书。
4+
5+
## 前提条件
6+
7+
### Namecheap API 启用
8+
9+
1. 登录 Namecheap 账户
10+
2. 进入 **Profile > Tools > Namecheap API Access**
11+
3. 启用 API 访问并获取 API 密钥
12+
4. 添加你的客户端 IP 到白名单
13+
14+
### 所需凭据
15+
16+
- `NAMECHEAP_USERNAME`：Namecheap 用户名
17+
- `NAMECHEAP_API_KEY`：API 密钥
18+
- `NAMECHEAP_CLIENT_IP`：客户端 IP 地址
19+
20+
## 使用方法
21+
22+
### 1. Docker Compose 配置
23+
24+
```yaml
25+
services:
26+
dstack-ingress:
27+
image: kvin/dstack-ingress@sha256:b61d50360c7a4e5ab7d22f5ce87677714f3f64a65db34ee5eebcc54683950c89
28+
ports:
29+
- "443:443"
30+
environment:
31+
# 设置 DNS 提供商为 namecheap
32+
- DNS_PROVIDER=namecheap
33+
34+
# Namecheap 凭据
35+
- NAMECHEAP_USERNAME=${NAMECHEAP_USERNAME}
36+
- NAMECHEAP_API_KEY=${NAMECHEAP_API_KEY}
37+
- NAMECHEAP_CLIENT_IP=${NAMECHEAP_CLIENT_IP}
38+
39+
# 通用设置
40+
- DOMAIN=${DOMAIN}
41+
- GATEWAY_DOMAIN=${GATEWAY_DOMAIN}
42+
- CERTBOT_EMAIL=${CERTBOT_EMAIL}
43+
- SET_CAA=true
44+
- TARGET_ENDPOINT=http://app:80
45+
volumes:
46+
- /var/run/tappd.sock:/var/run/tappd.sock
47+
- cert-data:/etc/letsencrypt
48+
restart: unless-stopped
49+
50+
app:
51+
image: nginx
52+
restart: unless-stopped
53+
54+
volumes:
55+
cert-data:
56+
```
57+
58+
### 2. 环境变量配置
59+
60+
创建 `.env` 文件：
61+
62+
```bash
63+
# DNS 提供商选择（cloudflare 或 namecheap）
64+
DNS_PROVIDER=namecheap
65+
66+
# Namecheap 配置
67+
NAMECHEAP_USERNAME=your-username
68+
NAMECHEAP_API_KEY=your-api-key
69+
NAMECHEAP_CLIENT_IP=your-client-ip
70+
71+
# 域名配置
72+
DOMAIN=your-domain.com
73+
GATEWAY_DOMAIN=your-gateway.com
74+
[email protected]
75+
```
76+
77+
### 3. 启动容器
78+
79+
```bash
80+
docker-compose up -d
81+
```
82+
83+
## 单独测试 Namecheap DNS 脚本
84+
85+
### 设置环境变量
86+
87+
```bash
88+
export NAMECHEAP_USERNAME="your-username"
89+
export NAMECHEAP_API_KEY="your-api-key"
90+
export NAMECHEAP_CLIENT_IP="your-client-ip"
91+
```
92+
93+
### 测试命令
94+
95+
```bash
96+
# 获取域名信息
97+
./scripts/namecheap_dns.py get_zone_id --domain example.com
98+
99+
# 设置 CNAME 记录
100+
./scripts/namecheap_dns.py set_cname \
101+
--domain test.example.com \
102+
--content target.example.com
103+
104+
# 设置 TXT 记录
105+
./scripts/namecheap_dns.py set_txt \
106+
--domain _tapp-address.example.com \
107+
--content "app-id:443"
108+
109+
# 设置 CAA 记录（注意：Namecheap API 不支持，需手动添加）
110+
./scripts/namecheap_dns.py set_caa \
111+
--domain example.com \
112+
--caa-tag issue \
113+
--caa-value "letsencrypt.org"
114+
```
115+
116+
### 使用沙箱环境测试
117+
118+
```bash
119+
./scripts/namecheap_dns.py get_zone_id \
120+
--domain example.com \
121+
--sandbox
122+
```
123+
124+
## 验证测试结果
125+
126+
### 1. 检查容器日志
127+
128+
```bash
129+
docker logs <container_name>
130+
```
131+
132+
### 2. 验证 DNS 记录
133+
134+
```bash
135+
# 检查 CNAME 记录
136+
nslookup your-domain.com
137+
138+
# 检查 TXT 记录
139+
nslookup -type=TXT _tapp-address.your-domain.com
140+
141+
# 使用 dig 命令查看详细信息
142+
dig your-domain.com CNAME
143+
dig _tapp-address.your-domain.com TXT
144+
```
145+
146+
### 3. 测试 HTTPS 访问
147+
148+
```bash
149+
# 测试 SSL 证书
150+
curl -I https://your-domain.com
151+
152+
# 查看证书详情
153+
openssl s_client -connect your-domain.com:443 -servername your-domain.com
154+
```
155+
156+
### 4. 检查证书文件
157+
158+
```bash
159+
# 进入容器查看证书
160+
docker exec -it <container_name> bash
161+
ls -la /etc/letsencrypt/live/$DOMAIN/
162+
```
163+
164+
## 切换回 Cloudflare
165+
166+
如果需要切换回 Cloudflare，只需修改环境变量：
167+
168+
```bash
169+
# 设置 DNS 提供商为 cloudflare（或删除此变量使用默认值）
170+
DNS_PROVIDER=cloudflare
171+
172+
# Cloudflare 配置
173+
CLOUDFLARE_API_TOKEN=your-cloudflare-token
174+
CLOUDFLARE_ZONE_ID=your-zone-id # 可选，会自动获取
175+
```
176+
177+
## 注意事项
178+
179+
### Namecheap 限制
180+
181+
1. **CAA 记录**：Namecheap API 目前不支持 CAA 记录，需要手动在控制面板添加
182+
2. **域名要求**：域名必须在 Namecheap 注册且使用 Namecheap DNS
183+
3. **IP 白名单**：客户端 IP 必须在 API 设置中白名单
184+
4. **API 限制**：有速率限制，避免频繁调用
185+
186+
### 故障排除
187+
188+
1. **API 错误**：检查用户名、API 密钥和 IP 白名单设置
189+
2. **域名不存在**：确认域名在 Namecheap 注册且使用其 DNS 服务
190+
3. **证书申请失败**：检查域名解析和 Let's Encrypt 限制
191+
4. **权限错误**：确保脚本有执行权限
192+
193+
### 安全建议
194+
195+
1. 使用环境变量而不是硬编码凭据
196+
2. 限制 API 密钥的访问权限
197+
3. 定期轮换 API 密钥
198+
4. 监控 DNS 变更日志
199+
200+
## 支持的功能
201+
202+
- ✅ 自动 SSL 证书申请和续期
203+
- ✅ CNAME 记录管理
204+
- ✅ TXT 记录管理
205+
- ⚠️ CAA 记录（需手动设置）
206+
- ✅ 多域名支持
207+
- ✅ 通配符证书支持

‎custom-domain/custom-domain/dstack-ingress/DNS_PROVIDERS.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# DNS Provider Configuration Guide
2+
3+
This guide explains how to configure dstack-ingress to work with different DNS providers for managing custom domains and SSL certificates.
4+
5+
## Supported DNS Providers
6+
7+
- **Cloudflare** - The original and default provider
8+
- **Linode DNS** - For Linode-hosted domains
9+
- **Namecheap DNS** - For Namecheap-hosted domains
10+
11+
## Environment Variables
12+
13+
### Common Variables (Required for all providers)
14+
15+
- `DOMAIN` - Your custom domain (e.g., `app.example.com`)
16+
- `GATEWAY_DOMAIN` - dstack gateway domain (e.g., `_.dstack-prod5.phala.network`)
17+
- `CERTBOT_EMAIL` - Email for Let's Encrypt registration
18+
- `TARGET_ENDPOINT` - Backend application endpoint to proxy to
19+
- `DNS_PROVIDER` - DNS provider to use (`cloudflare`, `linode`, `namecheap`)
20+
21+
### Optional Variables
22+
23+
- `SET_CAA` - Enable CAA record setup (default: false)
24+
- `PORT` - HTTPS port (default: 443)
25+
- `TXT_PREFIX` - Prefix for TXT records (default: "_tapp-address")
26+
27+
## Provider-Specific Configuration
28+
29+
### Cloudflare
30+
31+
```bash
32+
DNS_PROVIDER=cloudflare
33+
CLOUDFLARE_API_TOKEN=your-api-token
34+
```
35+
36+
**Required Permissions:**
37+
- Zone:Read
38+
- DNS:Edit
39+
40+
### Linode DNS
41+
42+
```bash
43+
DNS_PROVIDER=linode
44+
LINODE_API_TOKEN=your-api-token
45+
```
46+
47+
**Required Permissions:**
48+
- Domains: Read/Write access
49+
50+
**Important Note for Linode:**
51+
- Linode has a limitation where CAA and CNAME records cannot coexist on the same subdomain
52+
- To work around this, the system will attempt to use A records instead of CNAME records
53+
- If the gateway domain can be resolved to an IP, an A record will be created
54+
- If resolution fails, it falls back to CNAME (but CAA records won't work on that subdomain)
55+
- This is a Linode-specific limitation not present in other providers
56+
57+
### Namecheap DNS
58+
59+
```bash
60+
DNS_PROVIDER=namecheap
61+
NAMECHEAP_USERNAME=your-namecheap-username
62+
NAMECHEAP_API_KEY=your-namecheap-api-key
63+
NAMECHEAP_CLIENT_IP=your-client-ip
64+
```
65+
66+
**Required Configuration:**
67+
- Namecheap username and API key from your Namecheap account
68+
- Client IP address (whitelisted in Namecheap API settings)
69+
70+
**Important Notes for Namecheap:**
71+
- Namecheap API requires whitelisting your IP address in their control panel
72+
- Namecheap does not support CAA records through their API - these must be configured manually
73+
- DNS propagation may take longer than other providers (up to 15 minutes)
74+
- Use sandbox mode for testing by setting `NAMECHEAP_SANDBOX=true`
75+
76+
## Docker Compose Example
77+
78+
```yaml
79+
version: '3.8'
80+
81+
services:
82+
ingress:
83+
image: dstack-ingress:latest
84+
ports:
85+
- "443:443"
86+
environment:
87+
# Common configuration
88+
- DNS_PROVIDER=linode
89+
- DOMAIN=app.example.com
90+
- GATEWAY_DOMAIN=_.dstack-prod5.phala.network
91+
- [email protected]
92+
- TARGET_ENDPOINT=http://backend:8080
93+
94+
# Linode specific
95+
- LINODE_API_TOKEN=your-api-token
96+
volumes:
97+
- ./letsencrypt:/etc/letsencrypt
98+
- ./evidences:/evidences
99+
```
100+
101+
## Migration from Cloudflare-only Setup
102+
103+
If you're currently using the Cloudflare-only version:
104+
105+
1. **No changes needed for Cloudflare users** - The default behavior remains Cloudflare
106+
2. **For other providers** - Add the `DNS_PROVIDER` environment variable and provider-specific credentials
107+
108+
## Troubleshooting
109+
110+
### DNS Provider Detection
111+
112+
If you see "Could not detect DNS provider type", ensure you have either:
113+
- Set `DNS_PROVIDER` environment variable explicitly, OR
114+
- Set provider-specific credential environment variables (e.g., `CLOUDFLARE_API_TOKEN`)
115+
116+
### Certificate Generation Issues
117+
118+
Different providers may have different propagation times. The default is 120 seconds, but you may need to adjust based on your provider's behavior.
119+
120+
### Permission Errors
121+
122+
Ensure your API tokens/credentials have the necessary permissions listed above for your provider.
123+
124+
## API Token Generation
125+
126+
### Cloudflare
127+
1. Go to https://dash.cloudflare.com/profile/api-tokens
128+
2. Create token with Zone:Read and DNS:Edit permissions
129+
3. Scope to specific zones if desired
130+
131+
### Linode
132+
1. Go to https://cloud.linode.com/profile/tokens
133+
2. Create a Personal Access Token
134+
3. Grant "Domains" Read/Write access
135+
136+
### Namecheap
137+
1. Go to https://www.namecheap.com/myaccount/api-settings/
138+
2. Enable API access and whitelist your IP address
139+
3. Note your API key and username
140+
4. For testing, use the sandbox environment at https://www.sandbox.namecheap.com/

0 commit comments

Comments
 (0)