# nginx-manager

**Repository Path**: wehxr/nginx-manager

## Basic Information

- **Project Name**: nginx-manager
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Nginx 集群管理（Agent 模式）

基于 Agent 的 Nginx 集群管理：控制端（Go）+ Agent（Go），参考 [Nginx Proxy Manager](https://github.com/NginxProxyManager/nginx-proxy-manager) 的常用能力。

## 功能

- **集群统一配置**：反向代理、证书、访问列表均为集群全局，一次编辑同步到所有已启用节点；任一节点同步失败则已成功节点自动回滚，保证一致性
- **节点管理**：Agent 注册、心跳；支持禁用节点（维护/下线），禁用后不参与同步，恢复后 Agent 启动时自动从控制端拉取配置并应用
- **证书管理**：自定义证书（上传 crt/key）、占位 Let's Encrypt（可后续接 certbot）
- **反向代理**：按域名转发到后端，支持 HTTP/HTTPS、自定义端口
- **基础认证**：HTTP Basic Auth（bcrypt），按访问列表绑定到代理
- **配置下发**：控制端生成 Nginx 配置，通过回调接口下发给所有已启用 Agent 写盘并 `nginx -s reload`

## 项目结构

```
cmd/control     # 控制端入口
cmd/agent       # Agent 入口
internal/       # 控制端内部：api、store、nginx 配置生成、config
agent/          # Agent：client、runner、callback、config
pkg/types       # 共享类型
docs/           # 文档
```

**接口文档与工作流程** 见 **[docs/api-and-workflow.md](docs/api-and-workflow.md)**。

---

## 快速开始

### 完整构建与运行步骤

**1. 前端构建（必须）**

```bash
cd frontend
npm install
npm run build
```

构建产物会输出到 `internal/web/static`，这些静态资源**必须**在后续 Go 编译前构建完成，因为 Go 代码会通过 `embed` 指令将这些文件打包进二进制文件中。这是实现跨平台部署的关键步骤 - 打包后的二进制文件可以在任何平台上独立运行，无需额外依赖前端文件。

**2. 后端编译（必须）**

```bash
cd /data/Codes/nginx-manager   # 返回项目根目录

go build -o bin/control ./cmd/control
go build -o bin/agent   ./cmd/agent
```

编译后的 `bin/control` 和 `bin/agent` 二进制文件已包含所有必要的资源（包括前端静态文件），可以直接部署到任何支持 Go 的平台上运行。

**跨平台编译示例**：

```bash
# 编译 Linux AMD64 版本
GOOS=linux GOARCH=amd64 go build -o bin/control-linux-amd64 ./cmd/control
GOOS=linux GOARCH=amd64 go build -o bin/agent-linux-amd64 ./cmd/agent

# 编译 Windows AMD64 版本
GOOS=windows GOARCH=amd64 go build -o bin/control-windows-amd64.exe ./cmd/control
GOOS=windows GOARCH=amd64 go build -o bin/agent-windows-amd64.exe ./cmd/agent

# 编译 macOS ARM64 版本（Apple Silicon）
GOOS=darwin GOARCH=arm64 go build -o bin/control-darwin-arm64 ./cmd/control
GOOS=darwin GOARCH=arm64 go build -o bin/agent-darwin-arm64 ./cmd/agent
```

**3. 启动控制端**

```bash
cp config.yaml.example config.yaml   # 首次运行
./bin/control -config config.yaml
```

浏览器访问：**http://控制端地址:8080/** 或 **http://控制端地址:8080/ui/** 打开 Web 管理页。

**4. 启动 Agent（可选）**

```bash
cp agent.yaml.example agent.yaml      # 首次运行，再按需改 control_host/port、listen_host/port
./bin/agent -config agent.yaml
```

## 许可证

MIT