firewall-system/README.md

# Firewall Management System

![License](https://img.shields.io/badge/license-MIT-blue.svg)  
![Go Version](https://img.shields.io/badge/go-1.20%2B-brightgreen)  
![Vue Version](https://img.shields.io/badge/vue-3.2%2B-brightgreen)

Firewall Management System 是一个基于 Go 和 Vue3 的防火墙管理系统，支持多用户、IP 白名单管理、黑名单管理以及管理员审批流程。通过自动获取用户 IP 地址，简化了 IP 白名单的申请和审批流程。

---

## 功能特性

- **用户管理**
  - 普通用户注册与登录
  - 管理员账户管理
  - 多级权限控制（普通用户、管理员、超级管理员）

- **IP 白名单管理**
  - 自动获取用户 IP 地址
  - 用户申请 IP 白名单
  - 管理员审批 IP 请求
  - 自动更新 iptables 规则

- **黑名单管理**
  - 支持按用户或 IP 封禁
  - 自动撤销被封禁用户的 IP 权限
  - 实时同步 iptables 规则

- **安全特性**
  - Cloudflare Turnstile 验证码
  - 请求频率限制
  - 审计日志记录
  - 会话管理加固

- **部署支持**
  - 支持 Docker 容器化部署
  - Systemd 服务管理
  - Nginx 反向代理配置

---

## 技术栈

- **后端**
  - Go 1.20+
  - Gorilla Mux 路由
  - SQLite 数据库
  - iptables 规则管理

- **前端**
  - Vue 3
  - Pinia 状态管理
  - Vite 构建工具
  - Axios HTTP 客户端

- **部署**
  - Docker
  - Systemd
  - Nginx

---

## 安装与部署

### 1. 环境要求

- Linux 服务器（推荐 Ubuntu 22.04 LTS）
- Go 1.20+
- Node.js 16+
- SQLite3
- iptables

### 2. 克隆项目

```bash
git clone hhttps://code.kcpot.top/QuarkTree/firewall-system.git
cd firewall-system
```

### 3. 配置环境变量

在 `backend/config/.env` 中配置以下变量：

```env
SESSION_SECRET="your-32byte-secret-key"
CF_SITE_KEY="your-cloudflare-sitekey"
CF_SECRET_KEY="your-cloudflare-secret"
DEFAULT_ADMIN="superadmin"
DEFAULT_ADMIN_PASS="SecurePass123!"
```

### 4. 初始化数据库

```bash
sqlite3 backend/db/firewall.db < backend/scripts/init_db.sql
```

### 5. 初始化管理员账户

```bash
chmod +x backend/scripts/init_admin.sh
./backend/scripts/init_admin.sh
```

### 6. 构建与运行

#### 后端

```bash
cd backend
go mod tidy
go build -o firewall
sudo ./firewall
```

#### 前端

```bash
cd frontend
npm install
npm run build
npx serve -s dist -p 3000
```

### 7. 使用 Docker 部署

```bash
cd deploy/docker
docker-compose up -d
```

---

## 配置文件

### Nginx 配置 (`deploy/nginx/firewall.conf`)

```nginx
server {
    listen 80;
    server_name firewall.example.com;

    location /api {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location / {
        root /var/www/firewall-frontend;
        try_files $uri $uri/ /index.html;
    }
}
```

### Systemd 服务文件 (`deploy/systemd/firewall.service`)

```ini
[Unit]
Description=Firewall Management Service
After=network.target

[Service]
EnvironmentFile=/opt/firewall/config/.env
WorkingDirectory=/opt/firewall/backend
ExecStart=/usr/local/bin/firewall
Restart=always
User=firewall-user

[Install]
WantedBy=multi-user.target
```

---

## 使用指南

### 1. 用户注册与登录

- 访问 `/register` 注册新用户
- 访问 `/login` 登录系统

### 2. 申请 IP 白名单

- 登录后访问 `/user/dashboard`
- 点击“申请新 IP”按钮

### 3. 管理员审批

- 管理员登录后访问 `/admin/dashboard`
- 查看待审批请求并批准或拒绝

### 4. 黑名单管理

- 管理员访问 `/admin/blacklist`
- 添加或移除黑名单条目

---

## API 文档

### 公共接口

- `POST /api/register` - 用户注册
- `POST /api/login` - 用户登录

### 用户接口

- `POST /api/user/request` - 申请 IP 白名单
- `GET /api/user/requests` - 获取用户请求状态

### 管理接口

- `GET /api/admin/requests` - 获取待审批请求
- `POST /api/admin/approve` - 批准或拒绝请求
- `POST /api/admin/blacklist` - 管理黑名单

---

## 贡献指南

欢迎提交 Issue 和 Pull Request！  
请确保代码风格一致，并通过所有测试。

---

## 许可证

本项目采用 [MIT 许可证](LICENSE)。