caddy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Caddy Local Proxy Manager

Caddy本地代理管理器

Manage local development reverse proxies via Caddy's Admin API at

localhost:2019

通过

localhost:2019

上的Caddy Admin API管理本地开发反向代理。

Session Naming

会话命名

When registering a proxy, use one of these approaches:

User provides name: Use exactly what they specify
Generate from context: Use project directory name + short random suffix (e.g.,
```
myapp-x7k2
```
)

Example generation:

bash

NAME="$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g')-$(head -c4 /dev/urandom | xxd -p | head -c4)"

注册代理时，可采用以下方式之一：

用户提供名称：完全使用用户指定的名称
从上下文生成：使用项目目录名称+短随机后缀（例如：
```
myapp-x7k2
```
）

示例生成：

bash

NAME="$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g')-$(head -c4 /dev/urandom | xxd -p | head -c4)"

Quick Reference

快速参考

Task	Command
Check status	`curl -sf http://localhost:2019/config/`
List routes	`curl -sf http://localhost:2019/config/apps/http/servers/local_proxies/routes`
Add route	`POST /config/apps/http/servers/local_proxies/routes`
Delete route	`DELETE /id/proxy_<name>`

任务	命令
检查状态	`curl -sf http://localhost:2019/config/`
列出路由	`curl -sf http://localhost:2019/config/apps/http/servers/local_proxies/routes`
添加路由	`POST /config/apps/http/servers/local_proxies/routes`
删除路由	`DELETE /id/proxy_<name>`

Workflows

工作流程

Check Caddy Status

检查Caddy状态

bash

curl -sf http://localhost:2019/config/ 2>/dev/null

If fails: "Caddy not running. Install:

brew install caddy

, Start:

caddy start

bash

curl -sf http://localhost:2019/config/ 2>/dev/null

如果失败："Caddy未运行。安装：

brew install caddy

，启动：

caddy start

List All Proxies

列出所有代理

bash

curl -sf http://localhost:2019/config/apps/http/servers/local_proxies/routes 2>/dev/null

Display as table: Name | URL | Backend

bash

curl -sf http://localhost:2019/config/apps/http/servers/local_proxies/routes 2>/dev/null

以表格形式显示：名称 | URL | 后端

Register a Proxy

注册代理

Get or generate name (ask user or generate from project + random)
Find available port (if not specified):

bash

for port in $(seq 3000 3100); do
  lsof -i :$port > /dev/null 2>&1 || { echo $port; break; }
done

Initialize server if needed:

bash

curl -sf http://localhost:2019/config/apps/http/servers/local_proxies > /dev/null 2>&1 || \
curl -sf -X POST http://localhost:2019/load \
  -H "Content-Type: application/json" \
  -d '{"apps":{"http":{"servers":{"local_proxies":{"listen":[":80"],"routes":[]}}}}}'

Add route (replace NAME and PORT):

bash

curl -sf -X POST "http://localhost:2019/config/apps/http/servers/local_proxies/routes" \
  -H "Content-Type: application/json" \
  -d '{"@id":"proxy_NAME","match":[{"host":["NAME.localhost"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"localhost:PORT"}]}],"terminal":true}'

Report: "Registered: http://NAME.localhost → localhost:PORT"

获取或生成名称（询问用户或从项目+随机字符串生成）
查找可用端口（如果未指定）：

bash

for port in $(seq 3000 3100); do
  lsof -i :$port > /dev/null 2>&1 || { echo $port; break; }
done

如有需要初始化服务器：

bash

curl -sf http://localhost:2019/config/apps/http/servers/local_proxies > /dev/null 2>&1 || \
curl -sf -X POST http://localhost:2019/load \
  -H "Content-Type: application/json" \
  -d '{"apps":{"http":{"servers":{"local_proxies":{"listen":[":80"],"routes":[]}}}}}'

添加路由（替换NAME和PORT）：

bash

curl -sf -X POST "http://localhost:2019/config/apps/http/servers/local_proxies/routes" \
  -H "Content-Type: application/json" \
  -d '{"@id":"proxy_NAME","match":[{"host":["NAME.localhost"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"localhost:PORT"}]}],"terminal":true}'

反馈结果："已注册：http://NAME.localhost → localhost:PORT"

Remove a Proxy

删除代理

bash

curl -sf -X DELETE "http://localhost:2019/id/proxy_NAME"

bash

curl -sf -X DELETE "http://localhost:2019/id/proxy_NAME"

Update a Proxy

更新代理

Delete then re-add with new port.

先删除再重新添加新端口的代理。

Route JSON Structure

路由JSON结构

json

{
  "@id": "proxy_<name>",
  "match": [{"host": ["<name>.localhost"]}],
  "handle": [{"handler": "reverse_proxy", "upstreams": [{"dial": "localhost:<port>"}]}],
  "terminal": true
}

json

{
  "@id": "proxy_<name>",
  "match": [{"host": ["<name>.localhost"]}],
  "handle": [{"handler": "reverse_proxy", "upstreams": [{"dial": "localhost:<port>"}]}],
  "terminal": true
}

Error Handling

错误处理

Error	Solution
Caddy not running	`brew install caddy && caddy start`
Port 80 denied	`sudo caddy start`
Route exists	Ask to update or pick different name

错误	解决方案
Caddy未运行	`brew install caddy && caddy start`
80端口权限被拒绝	`sudo caddy start`
路由已存在	询问用户是否更新或选择其他名称

Platform Notes

平台说明

macOS:
```
*.localhost
```
resolves to 127.0.0.1 automatically
Linux: May need
```
/etc/hosts
```
entries

macOS：
```
*.localhost
```
会自动解析到127.0.0.1
Linux：可能需要添加
```
/etc/hosts
```
条目