Metadata-Version: 2.4
Name: sing-box-config
Version: 0.7.0
Summary: Yet another configuration generator for sing-box
Project-URL: Homepage, https://github.com/ak1ra-lab/sing-box-tproxy
Project-URL: Changelog, https://github.com/ak1ra-lab/sing-box-tproxy/blob/master/CHANGELOG.md
Author-email: ak1ra <git@ak1ra.xyz>
License-Expression: MIT
License-File: LICENSE
Keywords: ansible,sing-box,tproxy
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: argcomplete>=3.6.2
Requires-Dist: chaos-utils>=0.3.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: tenacity>=9.1.2
Description-Content-Type: text/markdown

# sing-box-tproxy

![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ak1ra-lab/sing-box-tproxy/.github%2Fworkflows%2Fpublish-to-pypi.yaml)
![PyPI - Downloads](https://img.shields.io/pypi/dm/sing-box-config)
![PyPI - Version](https://img.shields.io/pypi/v/sing-box-config)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ak1ra-lab/sing-box-tproxy)

使用 Ansible 自动部署 [SagerNet/sing-box](https://github.com/SagerNet/sing-box) TPROXY 透明代理.

## 特性

- 🚀 三种部署模式: mixed (代理) / local (本机透明代理) / gateway (网关)
- 🔄 自动订阅更新与节点管理
- ⚙️ systemd 服务与配置热重载
- 🛡️ nftables + fwmark 策略路由
- 📦 Python 配置生成工具 ([PyPI](https://pypi.org/project/sing-box-config/))

## 快速开始

### 前置要求

- 目标主机: Debian/Ubuntu Linux
- Ansible core >= 2.18

### sing-box 透明代理网关部署

1. 克隆仓库

   ```shell
   git clone https://github.com/ak1ra-lab/sing-box-tproxy.git
   cd sing-box-tproxy
   ```

2. 配置 inventory

   编辑 `~/.ansible/inventory/hosts.yaml`:

   ```yaml
   all:
     hosts:
       gateway:
         ansible_host: 10.0.42.253
         ansible_user: debian
   ```

3. 准备 host_vars (或 group_vars) 并在其中添加订阅信息

   ```shell
   vim playbooks/host_vars/gateway/all.yml
   ```

   内容示例:

   ```yaml
   sing_box_config_subscriptions:
     my_provider:
       type: remote
       format: sip002
       enabled: true
       url: "https://example.com/api/subscribe?token=xxx"
   ```

4. 执行部署

   ```shell
   ansible-playbook playbooks/sing_box_tproxy.yaml -v
   ```

5. 验证服务

   ```shell
   ssh gateway
   systemctl status sing-box
   ```

## 部署模式

| 模式      | 场景     | 透明代理 | IP 转发 | TPROXY 监听 |
| --------- | -------- | -------- | ------- | ----------- |
| `mixed`   | 手动代理 | ❌       | ❌      | N/A         |
| `local`   | 工作站   | ✅ 本机  | ❌      | 127.0.0.1   |
| `gateway` | 网关     | ✅ 全网  | ✅      | 0.0.0.0     |

配置方式: 在 `playbooks/sing_box_tproxy.yaml` 或 `playbooks/host_vars/` 目录下设置 `sing_box_mode` 变量.

> 注意:
>
> - Ansible Playbook 中的 vars 优先级高于 `host_vars/`.
> - gateway 模式下 TPROXY 必须监听 0.0.0.0 以处理来自局域网设备的流量.

## sing-box 服务端部署

本项目也提供了快速部署 sing-box 服务端的功能 (Shadowsocks, Trojan, Hysteria2 等).

1. 配置 inventory

   ```yaml
   all:
     hosts:
       vps:
         ansible_host: 1.2.3.4
         ansible_user: root
   ```

2. 为 vps 准备 host_vars (或 group_vars), 提供部署服务端的所需 vars

   ```shell
   vim playbooks/host_vars/vps/all.yml
   ```

   ```yaml
   sing_box_server_hostname: "vps.example.com"

   sing_box_server_region: us
   sing_box_server_user_count: 1

   # Enable protocols
   sing_box_server_enable_shadowsocks: true
   sing_box_server_enable_trojan: true
   sing_box_server_enable_hysteria2: true
   sing_box_server_enable_vless: false
   sing_box_server_enable_tuic: false

   # TLS with ACME DNS-01
   sing_box_server_tls_mode: acme
   sing_box_server_acme_email: "acme@example.com"
   sing_box_server_acme_use_dns01: true
   sing_box_server_acme_dns01_provider: cloudflare
   sing_box_server_acme_dns01_cloudflare_api_token: "<replace-with-your-cloudflare-token>"
   ```

3. 执行部署, 该 Playbook 会自动生成客户端配置并打印在输出中.

   ```shell
   ansible-playbook playbooks/sing_box_server.yaml -v
   ```

## 文档

详细文档请参考:

- `docs/architecture.md`
  - 架构设计, 透明代理原理, fwmark 机制, nftables 规则详解

## 项目结构

```
sing-box-tproxy/
├── src/sing_box_config/     # Python 配置生成工具
├── playbooks/               # playbooks 目录
│   ├── sing_box_tproxy.yaml # sing-box 透明代理 playbook
│   └── sing_box_server.yaml # sing-box 服务端部署 playbook
├── roles/                   # Ansible 角色
│   ├── sing_box_install/    # 安装 sing-box
│   ├── sing_box_config/     # 安装 Python 配置生成工具
│   ├── sing_box_tproxy/     # 透明代理 (nftables/策略路由)
│   └── sing_box_server/     # 创建 sing-box 服务端配置文件
├── docs/                    # 文档
│   └── architecture.md      # 架构设计文档
└── README.md                # 本文件
```

## License

MIT License. See `LICENSE` file for details.

## 参考资料

- [sing-box 官方文档](https://sing-box.sagernet.org/)
- [sing-box tproxy inbound](https://sing-box.sagernet.org/configuration/inbound/tproxy/)
- [sing-box tproxy 透明代理教程](https://lhy.life/20231012-sing-box-tproxy/)
- [nftables wiki](https://wiki.nftables.org/)
- [SIP002 URI Scheme](https://github.com/shadowsocks/shadowsocks-org/wiki/SIP002-URI-Scheme)
- [Ansible Documentation](https://docs.ansible.com/)
