249 lines
6.4 KiB
Markdown
249 lines
6.4 KiB
Markdown
# HostSync
|
||
|
||
强大的命令行 Hosts 文件管理工具，支持分块管理、智能 DNS 解析和定时自动更新。
|
||
|
||
## ✨ 功能特点
|
||
|
||
- 🎯 **分块管理** - 按名称组织 Hosts 配置，支持独立启用/禁用
|
||
- 🌐 **智能解析** - 支持 DNS、DoH、预设服务器多种解析方式
|
||
- 🔄 **自动更新** - 一键更新域名 IP，支持定时任务
|
||
- 🔧 **服务模式** - 后台服务运行，跨平台支持
|
||
- 📦 **安全可靠** - 自动备份，权限管理，格式化清理
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 🎯 一键安装（推荐）
|
||
|
||
**Windows (PowerShell):**
|
||
|
||
```powershell
|
||
iex (irm "https://git.xykqyy.com/ljp/hostSync/raw/branch/main/install.ps1")
|
||
```
|
||
|
||
**Linux/macOS:**
|
||
|
||
```bash
|
||
curl -fsSL https://git.xykqyy.com/ljp/hostSync/raw/branch/main/install.sh | bash
|
||
```
|
||
|
||
> [!TIP]
|
||
> 一键安装会自动下载最新版本、配置环境变量并完成初始化。支持多种参数，详见 [安装指南](INSTALL.md)。
|
||
|
||
### 📦 手动安装
|
||
|
||
1. **下载程序**
|
||
|
||
从 [Releases](./releases) 下载对应平台的可执行文件。
|
||
|
||
2. **初始化系统**
|
||
|
||
```bash
|
||
# Windows (管理员权限)
|
||
hostsync init
|
||
|
||
# Linux/macOS (sudo权限)
|
||
sudo hostsync init
|
||
```
|
||
|
||
### 3. 基本使用
|
||
|
||
```bash
|
||
# 查看配置
|
||
hostsync list
|
||
|
||
# 添加域名块
|
||
hostsync add github github.com
|
||
|
||
# 启用/禁用块
|
||
hostsync enable github
|
||
hostsync disable github
|
||
|
||
# 更新域名解析
|
||
hostsync update github
|
||
|
||
# 设置定时任务
|
||
hostsync cron github "0 0 2 * * *" # 每天凌晨2点更新
|
||
```
|
||
|
||
## 📋 命令参考
|
||
|
||
### 基础管理
|
||
|
||
| 命令 | 说明 | 示例 |
|
||
| --------------------------- | ----------- | ---------------------------------- |
|
||
| `list [block]` | 查看配置 | `hostsync list --raw` |
|
||
| `add <block> <domain> [ip]` | 添加记录 | `hostsync add dev api.test.com` |
|
||
| `remove <block> [domain]` | 删除记录/块 | `hostsync remove dev api.test.com` |
|
||
| `enable <block>` | 启用块 | `hostsync enable dev` |
|
||
| `disable <block>` | 禁用块 | `hostsync disable dev` |
|
||
|
||
### DNS 解析与更新
|
||
|
||
| 命令 | 说明 | 示例 |
|
||
| ---------------- | ------------- | ------------------------------------------------- |
|
||
| `update [block]` | 更新解析 | `hostsync update --dns 1.1.1.1` |
|
||
| `--dns <server>` | 指定 DNS | `hostsync update --dns 8.8.8.8` |
|
||
| `--doh <url>` | 使用 DoH | `hostsync update --doh https://1.1.1.1/dns-query` |
|
||
| `--srv <name>` | 预设服务器 | `hostsync update --srv Cloudflare` |
|
||
| `--save` | 保存 DNS 配置 | `hostsync update github --save` |
|
||
|
||
### 定时任务
|
||
|
||
| 命令 | 说明 | 示例 |
|
||
| --------------------- | ------------ | ------------------------------------ |
|
||
| `cron [block] [expr]` | 管理定时任务 | `hostsync cron github "0 0 2 * * *"` |
|
||
| `cron list` | 列出任务 | `hostsync cron list` |
|
||
|
||
**常用 cron 表达式 (6 字段格式: 秒 分 时 日 月 星期):**
|
||
|
||
- `0 0 0 * * *` - 每天午夜
|
||
- `0 0 */4 * * *` - 每 4 小时
|
||
- `0 0 9 * * 1` - 每周一上午 9 点
|
||
- `*/30 * * * * *` - 每 30 秒
|
||
- `0 */10 * * * *` - 每 10 分钟
|
||
|
||
### 系统服务
|
||
|
||
| 命令 | 说明 | 示例 |
|
||
| -------------------- | -------- | -------------------------- |
|
||
| `service install` | 安装服务 | `hostsync service install` |
|
||
| `service start/stop` | 启停服务 | `hostsync service start` |
|
||
| `service status` | 查看状态 | `hostsync service status` |
|
||
|
||
### 其他工具
|
||
|
||
| 命令 | 说明 | 示例 |
|
||
| -------------------- | -------- | --------------------------------- |
|
||
| `format [block]` | 格式化 | `hostsync format` |
|
||
| `server test [name]` | 测试 DNS | `hostsync server test Cloudflare` |
|
||
| `version` | 版本信息 | `hostsync version` |
|
||
|
||
## ⚙️ 配置说明
|
||
|
||
### 块格式示例
|
||
|
||
```text
|
||
# github:
|
||
140.82.114.3 github.com
|
||
185.199.108.133 avatars.githubusercontent.com
|
||
# useSrv: Cloudflare
|
||
# cronJob: 0 0 2 * * *
|
||
# updateAt: 2024-01-15 10:00:00
|
||
# github;
|
||
```
|
||
|
||
### DNS 配置选项
|
||
|
||
```text
|
||
# useDns: 1.1.1.1 # 直接DNS
|
||
# useDoh: https://1.1.1.1/dns-query # DoH服务器
|
||
# useSrv: Cloudflare # 预设服务器
|
||
```
|
||
|
||
## 💡 使用场景
|
||
|
||
### 开发环境管理
|
||
|
||
```bash
|
||
# 创建开发环境
|
||
hostsync add dev api.example.com 192.168.1.100
|
||
hostsync add dev web.example.com 192.168.1.101
|
||
hostsync enable dev
|
||
```
|
||
|
||
### GitHub 加速
|
||
|
||
```bash
|
||
# 添加GitHub相关域名
|
||
hostsync add github github.com
|
||
hostsync add github api.github.com
|
||
hostsync update github --srv Cloudflare
|
||
hostsync cron github "0 0 2 * * *" # 每天更新
|
||
```
|
||
|
||
### 多环境切换
|
||
|
||
```bash
|
||
# 生产环境
|
||
hostsync add prod api.myapp.com 1.2.3.4
|
||
|
||
# 测试环境
|
||
hostsync add test api.myapp.com 192.168.1.10
|
||
|
||
# 切换环境
|
||
hostsync disable prod && hostsync enable test
|
||
```
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 权限要求
|
||
|
||
- **Windows**: 必须以管理员权限运行
|
||
- **Linux/macOS**: 需要 sudo 权限访问 `/etc/hosts`
|
||
|
||
### 系统支持
|
||
|
||
- Windows 7/8/10/11 (Windows Service)
|
||
- Linux (systemd)
|
||
- macOS (LaunchD)
|
||
|
||
### 安全说明
|
||
|
||
- 程序仅在本地运行，不收集用户数据
|
||
- 修改前自动备份 hosts 文件
|
||
- 支持配置文件热重载
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **权限不足**: 确保以管理员/sudo 权限运行
|
||
2. **服务无法启动**: 检查系统服务支持 (systemd/LaunchD)
|
||
3. **DNS 解析失败**: 尝试更换 DNS 服务器 `hostsync server test`
|
||
4. **定时任务不执行**: 检查服务状态 `hostsync service status`
|
||
|
||
### 调试模式
|
||
|
||
```bash
|
||
hostsync update --debug # 启用详细日志
|
||
```
|
||
|
||
### 重置配置
|
||
|
||
```bash
|
||
hostsync init --force # 强制重新初始化
|
||
```
|
||
|
||
## 📁 配置文件位置
|
||
|
||
- **Windows**: `%USERPROFILE%\.hostsync\`
|
||
- **Linux/macOS**: `~/.hostsync/`
|
||
|
||
包含：配置文件、日志文件、备份文件、服务器配置
|
||
|
||
## 🛠️ 开发构建
|
||
|
||
### 构建要求
|
||
|
||
- Go 1.19+
|
||
- Git
|
||
- UPX (可选，用于压缩)
|
||
- GoReleaser (可选，用于发布)
|
||
|
||
### 构建命令
|
||
|
||
```bash
|
||
# Windows
|
||
.\build.ps1
|
||
|
||
# Linux/macOS
|
||
./build.sh
|
||
|
||
# 手动构建
|
||
go build -o hostsync main.go
|
||
```
|
||
|
||
## 📄 License
|
||
|
||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|