一、安装基础依赖(git、golang、rsync、python、socat)
bash
运行
# 更新软件源
sudo apt update
# 一次性安装全部依赖
sudo apt install -y git golang rsync python3 python3-pip socat python3-requests python3-pyquery
# pip 设置清华国内源
pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 校验Python依赖是否可用
python3 -c "import requests, pyquery; print('依赖正常')"
二、拉取 tunasync 同步脚本仓库(tunasync-scripts)
bash
运行
# 拉取官方同步脚本存放至 /etc/tunasync/scripts
sudo git clone shturl.cc/mvafWx1tZnaLMT3GBM6q01eBDBkMSqusUnXGfyzu6 /etc/tunasync/scripts
三、创建程序统一存放目录 /usr/local/tunasync
bash
运行
sudo mkdir -p /usr/local/tunasync
四、源码编译 Tunasync 二进制程序(放弃 github release 下载方案)
bash
运行
# Gitee国内镜像克隆源码到家目录
git clone shturl.cc/wsZnwKULSXhPRjT1REhlzBx1bx2SuZFTJNF ~/tunasync-src
# 进入源码目录编译
cd ~/tunasync-src
make
# 进入编译产物文件夹
cd ~/tunasync-src/build-linux-amd64
# 带权限移动程序到统一目录
sudo mv tunasync tunasynctl /usr/local/tunasync/
五、创建系统软链接,全局直接调用命令
bash
运行
sudo ln -s /usr/local/tunasync/tunasync /usr/local/bin/
sudo ln -s /usr/local/tunasync/tunasynctl /usr/local/bin/
六、验证安装是否成功
bash
运行
# 查看程序版本
tunasync --version
# 查看控制工具帮助文档
tunasynctl help
shitou@shitou:~/tunasync-src/build-linux-amd64$ tunasync --version
Version: 0.8.0
Git Hash: 755c87761daecf590b1192501a652b582d3eda6d
Build Date: 2026-07-08 01:31:58 +0000 UTC
shitou@shitou:~/tunasync-src/build-linux-amd64$ tunasynctl help
NAME:
tunasynctl - control client for tunasync manager
USAGE:
tunasynctl [global options] command [command options] [arguments...]
VERSION:
0.8.0
COMMANDS:
list List jobs of workers
flush Flush disabled jobs
workers List workers
rm-worker Remove a worker
set-size Set mirror size
start Start a job
stop Stop a job
disable Disable a job
restart Restart a job
reload Tell worker to reload configurations
ping
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--help, -h show help
--version, -v print the version
补充说明
你执行过
sudo wget下载官方二进制包,但最终选择源码编译方式,流程中直接舍弃下载压缩包步骤;/etc/tunasync/scripts存放各类源同步脚本(PyPI、Docker、npm、Debian 等),后续配置 worker 时会调用;所有写入
/usr/local系统目录操作必须加sudo,否则会出现Permission denied权限报错;Python 环境用于 tunasync 各类自定义同步脚本执行校验。
然后创建配套的目录
sudo mkdir -p /usr/local/tunasync/conf /usr/local/tunasync/log /usr/local/tunasync/db /data/mirrors/usr/local/tunasync/conf:存放 manager、worker 配置文件/usr/local/tunasync/log:同步运行日志,用于排查同步失败、卡死问题/usr/local/tunasync/db:bolt 持久化数据库,保存所有同步任务、定时状态/data/mirrors:Tunasync 同步所有软件源(PyPI、Ubuntu、Docker 等)的存储目录,对接 Nginx 网页访问
# 查看启用的网站配置文件,确认现有站点名称
ls /etc/nginx/sites-enabled/
# 读取mirror-iso完整配置,获取原有ISO、apt-mirror目录路径
cat /etc/nginx/sites-available/mirror-iso站点端口:listen 8081
旧 Ubuntu 源路径:/data/apt-mirror/mirror/mirrors.tuna.tsinghua.edu.cn/ubuntu/
ISO 镜像路径:/data/iso/
后续 Nginx 配置基于这 3 个路径改造,实现新旧镜像网页共存,不影响原有内网装机、软件源使用
写入 Worker 同步执行配置
写入 Worker 同步执行配置(命令 2031,核心同步规则)
bash
运行
sudo tee /usr/local/tunasync/conf/worker.conf <<'EOF'
[global]
name = "local-worker"
mirror_dir = "/data/mirrors"
concurrent = 2
log_path = "/usr/local/tunasync/log/worker.log"
script_base = "/etc/tunasync/scripts"
[manager]
api_base = "http://127.0.0.1:12345"
token = "Sync@2026Tuna"
# 任务1:rsync同步Ubuntu系统源(可替代旧apt-mirror)
[[mirrors]]
name = "ubuntu"
provider = "rsync"
upstream = "rsync://mirrors.tuna.tsinghua.edu.cn/ubuntu/"
interval = 3600
# 任务2:脚本同步PyPI Python包仓库
[[mirrors]]
name = "pypi"
provider = "command"
command = "./pypi/mirror.py"
interval = 86400
EOF
关键参数解释
mirror_dir = "/data/mirrors":同步文件最终存储目录,和 Nginx 根目录对应;
concurrent = 2:限制最大同时同步 2 个任务,避免占满服务器带宽 / 磁盘 IO;
script_base 绑定第二阶段下载的脚本仓库,是 PyPI 同步的依赖;
interval 单位秒:3600 = 每小时同步一次,86400 = 每日同步一次;
每一组 [[mirrors]] = 一条自动同步任务,可无限新增 CentOS、Docker、npm 等更新 mirror-iso Nginx 配置,新旧源共存
bash
运行
sudo tee /etc/nginx/sites-available/mirror-iso <<'EOF'
server {
listen 8081;
listen [::]:8081;
server_name _;
# Tunasync同步的所有软件源根目录 /data/mirrors
root /data/mirrors;
autoindex on;
autoindex_exact_size off;
autoindex_localtime on;
# 保留旧apt-mirror ubuntu源,兼容内网原有服务器,无需批量改机器源地址
location /ubuntu/ {
alias /data/apt-mirror/mirror/mirrors.tuna.tsinghua.edu.cn/ubuntu/;
autoindex on;
autoindex_exact_size off;
autoindex_localtime on;
}
# 原有系统ISO镜像目录完全不变,不影响装机下载镜像
location /iso/ {
alias /data/iso/;
autoindex on;
autoindex_exact_size off;
autoindex_localtime on;
}
# 大文件缓存优化,iso/deb安装包长期不变,浏览器缓存14天,减轻服务器读取压力
location ~* \.(iso|deb|gz|xz|zip|tar|sha256|whl)$ {
expires 14d;
add_header Cache-Control "public, no-transform";
}
# 禁止访问隐藏文件(数据库、日志等敏感文件)
location ~ /\. {
deny all;
}
}
EOF校验配置语法,防止Nginx崩溃
sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
shitou@shitou:~/tunasync-src/build-linux-amd64$ sudo systemctl reload nginx 平滑重载Nginx,不中断内网正在下载文件的用户
Nginx 配置完成后,网页访问效果
Tunasync 新同步源(PyPI、新版 Ubuntu、CentOS 等):
http://服务器IP:8081/旧 apt-mirror 遗留 Ubuntu 源:
http://服务器IP:8081/ubuntu/系统 ISO 镜像文件:
http://服务器IP:8081/iso/
============================================================================================
好问题!让我详细解释这两个配置文件的作用和它们之间的关系:
manager.conf - 调度中心配置文件
这是整个系统的"大脑",负责:
1. 任务调度
管理所有镜像同步任务的元数据
记录哪些任务该运行了(根据
interval时间间隔)决定什么时候触发 Worker 去执行同步
2. 状态存储
ini
[files]
db_type = "bolt" # 使用 BoltDB 嵌入式数据库
db_file = "/usr/local/tunasync/db/manager.db" # 数据库文件位置存储所有镜像任务的状态(成功/失败/运行中)
记录同步历史、下次执行时间
存储 Worker 的注册信息
3. API 服务
ini
[api]
addr = "127.0.0.1:14242" # 监听地址和端口
token = "Sync@2026Tuna" # 认证令牌提供 RESTful API 接口
Worker 通过这个 API 注册自己、上报状态
tunasynctl通过这个 API 查询/控制任务
4. Worker 管理
接收 Worker 注册
跟踪哪些 Worker 在线
分配任务给 Worker(虽然实际是 Worker 主动拉取任务)
worker.conf - 执行器配置文件
这是系统的"手脚",负责:
1. 指定要做什么(任务列表)
ini
[[mirrors]]
name = "ubuntu" # 任务名称
provider = "rsync" # 使用 rsync 方式
upstream = "rsync://mirrors.tuna.tsinghua.edu.cn/ubuntu/" # 上游源
interval = 3600 # 每3600秒(1小时)执行一次每个 [[mirrors]] 段定义一个同步任务。
2. 连接到 Manager
ini
[manager]
api_base = "http://127.0.0.1:14242" # Manager 的地址
token = "Sync@2026Tuna" # 认证令牌Worker 启动后向这个地址注册
定期向 Manager 上报任务状态
从 Manager 获取任务配置更新
3. 本地工作目录
ini
[global]
mirror_dir = "/data/mirrors" # 镜像存储路径
concurrent = 2 # 最大并发任务数
log_path = "/usr/local/tunasync/log/worker.log" # 日志路径它们是如何协作的?
text
┌─────────────────┐ ┌─────────────────┐
│ Manager │ │ Worker │
│ (调度中心) │◄────────┤ (执行器) │
│ │ 注册/上报 │ │
│ 端口: 14242 │────────►│ 执行同步任务 │
│ │ 下发配置 │ │
│ 存储任务状态 │ │ 存储镜像文件 │
│ 管理调度策略 │ │ 执行 rsync │
└─────────────────┘ └─────────────────┘
▲
│ 查询/控制
│
┌─────────────────┐
│ tunasynctl │
│ (管理工具) │
│ 查看任务状态 │
│ 手动触发同步 │
└─────────────────┘举个例子 - Ubuntu 镜像同步的完整流程:
Worker 启动 → 向 Manager (14242端口) 注册
Worker 读取配置,看到 ubuntu 任务每 3600 秒执行
Worker 执行
rsync rsync://mirrors.tuna.tsinghua.edu.cn/ubuntu/ → /data/mirrors/ubuntu/Worker 向 Manager 报告:"ubuntu 任务正在运行" → "ubuntu 任务完成/失败"
你可以在任何时候用
tunasynctl list查看所有任务状态
当前配置的问题和修改
之前的错误:
ini
# Worker 配置中
api_base = "http://127.0.0.1:12345" # ❌ Manager 在 14242,不是 12345修改后:
ini
# Worker 配置中
api_base = "http://127.0.0.1:14242" # ✓ 现在匹配了为什么要统一端口?
Manager 默认监听 14242 端口(你的配置中
listen_port = 12345没生效)Worker 必须连接到 Manager 实际监听的端口
tunasynctl也必须连接到这个端口如果不一致,就会出现
connection refused错误
配置的灵活性
你可以根据需求自由配置:
ini
# 多个镜像任务示例
[[mirrors]]
name = "ubuntu"
provider = "rsync"
upstream = "rsync://mirrors.aliyun.com/ubuntu/"
interval = 7200 # 每2小时同步一次
[[mirrors]]
name = "centos"
provider = "rsync"
upstream = "rsync://mirrors.tuna.tsinghua.edu.cn/centos/"
interval = 14400 # 每4小时同步一次
[[mirrors]]
name = "debian"
provider = "command" # 用脚本同步
command = "/etc/tunasync/scripts/sync_debian.sh"
interval = 86400 # 每天一次Worker 会按配置的间隔自动执行这些任务,Manager 负责记录和展示状态。
简单说:Manager 是管理者(大脑),Worker 是执行者(手脚),配置文件就是告诉它们"谁在哪、做什么、怎么做"。
方案1 修改worker.conf /usr/local/tunasync/conf/worker.conf
bash
cat > /usr/local/tunasync/conf/worker.conf <<'EOF'
[global]
name = "local-worker"
mirror_dir = "/data/mirrors"
concurrent = 2
log_path = "/usr/local/tunasync/log/worker.log"
script_base = "/etc/tunasync/scripts"
[manager]
api_base = "http://127.0.0.1:14242"
token = "Sync@2026Tuna"
[[mirrors]]
name = "ubuntu"
provider = "rsync"
upstream = "rsync://mirrors.tuna.tsinghua.edu.cn/ubuntu/"
interval = 3600
[[mirrors]]
name = "pypi"
provider = "command"
command = "./pypi/mirror.py"
interval = 86400
EOF
然后重启 Worker:
bash
pkill tunasync
sleep 1
# 终端1:启动 Manager
/usr/local/tunasync/tunasync manager -c /usr/local/tunasync/conf/manager.conf &
sleep 2
# 终端2:启动 Worker
/usr/local/tunasync/tunasync worker -c /usr/local/tunasync/conf/worker.conf
# 终端3:测试
/usr/local/tunasync/tunasynctl -u http://127.0.0.1:14242 -t Sync@2026Tuna list方案二 修正 Manager 配置,让它监听 12345 端口
先看看你现在的 manager.conf:
bash
cat /usr/local/tunasync/conf/manager.conf然后修正配置(Tunasync 0.8.0 的正确格式):
bash
cat > /usr/local/tunasync/conf/manager.conf <<'EOF'
[global]
name = "local-manager"
log_path = "/usr/local/tunasync/log/manager.log"
[api]
addr = "127.0.0.1:12345"
token = "Sync@2026Tuna"
[files]
db_type = "bolt"
db_file = "/usr/local/tunasync/db/manager.db"
EOF重启测试:
bash
pkill tunasync
sleep 1
/usr/local/tunasync/tunasync manager -c /usr/local/tunasync/conf/manager.conf &
sleep 2
sudo ss -tlnp | grep tunasyncrsync 同步下来的文件有些权限不对。修复一下:
bash
# 修复整个镜像目录的权限
sudo chown -R shitou:shitou /data/mirrors/ubuntu/
# 修复目录权限
sudo chmod -R 755 /data/mirrors/ubuntu/
同步进度说明
当前已同步 33MB,这是 rsync 刚开始
Ubuntu 完整源可能有几十GB,需要很长时间
可以用以下命令实时查看:
bash
watch -n 10 'du -sh /data/mirrors/ubuntu/ 2>/dev/null'
查看同步状态
bash
# 查看 Worker 日志
tail -f /usr/local/tunasync/log/worker.log
tunasynctl 0.8.0 版本的全局选项里没有 Manager 地址和 Token 参数。需要通过配置文件或环境变量来指定。
方法1:创建 tunasynctl 配置文件
bash
cat > ~/.tunasynctl.yaml <<'EOF'
manager: "http://127.0.0.1:14242"
token: "Sync@2026Tuna"
EOF
然后直接使用:
bash
/usr/local/tunasync/tunasynctl ping
/usr/local/tunasync/tunasynctl workers
/usr/local/tunasync/tunasynctl list
方法2:使用环境变量
bash
export TUNASYNC_MANAGER=http://127.0.0.1:14242
export TUNASYNC_TOKEN=Sync@2026Tuna
/usr/local/tunasync/tunasynctl ping
/usr/local/tunasync/tunasynctl workers
方法3:试试子命令是否有选项
bash
/usr/local/tunasync/tunasynctl ping --help
/usr/local/tunasync/tunasynctl workers --helpshitou@shitou:~$ /usr/local/tunasync/tunasynctl ping
Usage Error: cmd command receive just 1 required positional argument MIRROR and 1 optional argument WORKER
shitou@shitou:~$ /usr/local/tunasync/tunasynctl workers
[
{
"id": "local-worker",
"url": "http://:0/",
"token": "REDACTED",
"last_online": "2026-07-08T06:14:31.822453585Z",
"last_register": "2026-07-08T06:14:26.688403768Z"
}
]
shitou@shitou:~$ /usr/local/tunasync/tunasynctl list
Usage Error: jobs command need at least one arguments or "--all" flag.
shitou@shitou:~$
Worker 已经注册上了!调整一下命令用法:
shitou@shitou:~$ /usr/local/tunasync/tunasynctl list --all
[
{
"name": "ubuntu",
"is_master": true,
"status": "syncing",
"last_update": "0001-01-01 00:00:00 +0000",
"last_update_ts": -62135596800,
"last_started": "2026-07-08 06:14:31 +0000",
"last_started_ts": 1783491271,
"last_ended": "0001-01-01 00:00:00 +0000",
"last_ended_ts": -62135596800,
"next_schedule": "0001-01-01 00:00:00 +0000",
"next_schedule_ts": -62135596800,
"upstream": "rsync://mirrors.tuna.tsinghua.edu.cn/ubuntu/",
"size": "unknown"
}
]
shitou@shitou:~$ /usr/local/tunasync/tunasynctl ping
Usage Error: cmd command receive just 1 required positional argument MIRROR and 1 optional argument WORKER
shitou@shitou:~$ /usr/local/tunasync/tunasynctl workers
[
{
"id": "local-worker",
"url": "http://:0/",
"token": "REDACTED",
"last_online": "2026-07-08T06:14:31.822453585Z",
"last_register": "2026-07-08T06:14:26.688403768Z"
}
]
shitou@shitou:~$ /usr/local/tunasync/tunasynctl list
Usage Error: jobs command need at least one arguments or "--all" flag.
shitou@shitou:~$
shitou@shitou:~$ /usr/local/tunasync/tunasynctl list --all
[
{
"name": "ubuntu",
"is_master": true,
"status": "syncing",
"last_update": "0001-01-01 00:00:00 +0000",
"last_update_ts": -62135596800,
"last_started": "2026-07-08 06:14:31 +0000",
"last_started_ts": 1783491271,
"last_ended": "0001-01-01 00:00:00 +0000",
"last_ended_ts": -62135596800,
"next_schedule": "0001-01-01 00:00:00 +0000",
"next_schedule_ts": -62135596800,
"upstream": "rsync://mirrors.tuna.tsinghua.edu.cn/ubuntu/",
"size": "unknown"
}
]
shitou@shitou:~$ /usr/local/tunasync/tunasynctl list local-worker
[
{
"name": "ubuntu",
"worker": "local-worker",
"is_master": true,
"status": "syncing",
"last_update": "0001-01-01T00:00:00Z",
"last_started": "2026-07-08T06:14:31.800966072Z",
"last_ended": "0001-01-01T00:00:00Z",
"next_schedule": "0001-01-01T00:00:00Z",
"upstream": "rsync://mirrors.tuna.tsinghua.edu.cn/ubuntu/",
"size": "unknown",
"error_msg": ""
}
]
shitou@shitou:~$ /usr/local/tunasync/tunasynctl list local-worker ubuntu
Failed to correctly get information of jobs from at least one manager
shitou@shitou:~$ /usr/local/tunasync/tunasynctl ping local-worker
[26-07-08 06:31:44][ERROR] handleClientCmd case workerID == " " not implemented yet
Failed to correctly send command: HTTP status code is not 200:
shitou@shitou:~$ /usr/local/tunasync/tunasynctl workers
[
{
"id": "local-worker",
"url": "http://:0/",
"token": "REDACTED",
"last_online": "2026-07-08T06:14:31.822453585Z",
"last_register": "2026-07-08T06:14:26.688403768Z"
}
]
shitou@shitou:~$ /usr/local/tunasync/tunasynctl list --all
[
{
"name": "ubuntu",
"is_master": true,
"status": "syncing",
"last_update": "0001-01-01 00:00:00 +0000",
"last_update_ts": -62135596800,
"last_started": "2026-07-08 06:14:31 +0000",
"last_started_ts": 1783491271,
"last_ended": "0001-01-01 00:00:00 +0000",
"last_ended_ts": -62135596800,
"next_schedule": "0001-01-01 00:00:00 +0000",
"next_schedule_ts": -62135596800,
"upstream": "rsync://mirrors.tuna.tsinghua.edu.cn/ubuntu/",
"size": "unknown"
}
]
shitou@shitou:~$ /usr/local/tunasync/tunasynctl list local-worker ubuntu
Failed to correctly get information of jobs from at least one manager
shitou@shitou:~$ du -sh /data/mirrors/ubuntu/ 2>/dev/null
18G /data/mirrors/ubuntu/
shitou@shitou:~$
状态:
"status": "syncing"- 正在同步中已下载: 18GB
开始时间: 2026-07-08 06:14:31
上游源: rsync://mirrors.tuna.tsinghua.edu.cn/ubuntu/
⚠️ 小问题(不影响功能)
list local-worker ubuntu报错 - 可能是 0.8.0 版本的 bug,不影响同步ping命令未实现 - 版本限制last_update显示异常时间 - 同步完成后会更新
有用的命令
bash
# 查看所有任务(这个最有用)
/usr/local/tunasync/tunasynctl list --all
# 查看 Worker 列表
/usr/local/tunasync/tunasynctl workers
# 实时监控同步进度
watch -n 10 'du -sh /data/mirrors/ubuntu/ 2>/dev/null'
# 查看 Worker 日志
tail -f /usr/local/tunasync/log/worker.log预估完成时间
Ubuntu 全量源大约 100-200GB,以当前速度(16分钟下载18GB),可能需要 2-4小时完成首次同步。后续增量同步会很快。
同步完成后的操作
同步完成后 status 会变为 success 或 failed,然后可以:
添加更多镜像任务(CentOS、Debian 等)
配置定时任务 - Worker 会按
interval自动执行配置 Nginx 对外提供 HTTP 镜像服务
设置开机自启(systemd 服务)
当前问题已全部解决,Tunasync 系统正常运行中!
nginx
# Tunasync 管理面板(访问 /admin/ 进入)
location /admin/ {
alias /var/www/tunasync-admin/;
index index.html;
try_files $uri $uri/ /admin/index.html;
}
# Tunasync Manager API 反向代理
location /api/ {
proxy_pass http://127.0.0.1:14242/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
同时把 HTML 文件里的 const API_BASE = '/api'; 不用改,路径正好对上。
。
方案一:管理面板换端口(最简单)
比如用 8082,互不干扰:
plaintext
管理面板 → 8082 端口
镜像下载 → 8081 端口用方案二的话,你直接访问 http://IP:8081/admin/ 就能进管理面板,下载镜像还是原来的地址,一个端口搞定
要我帮你把完整的修改后配置拼出来吗?
方案二,的情况你给我整个写进去,
整合管理面板端口配置
完整配置,直接覆盖原文件:
bash
运行
sudo tee /etc/nginx/sites-available/mirror-iso <<'EOF'
server {
listen 8081;
listen [::]:8081;
server_name _;
# Tunasync同步的所有软件源根目录 /data/mirrors
root /data/mirrors;
autoindex on;
autoindex_exact_size off;
autoindex_localtime on;
# Tunasync 管理面板(访问 /admin/ 进入)
location ^~ /admin/ {
alias /var/www/tunasync-admin/;
index index.html;
try_files $uri $uri/ /admin/index.html;
}
# Tunasync Manager API 反向代理
location ^~ /api/ {
proxy_pass http://127.0.0.1:14242/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# 保留旧apt-mirror ubuntu源,兼容内网原有服务器,无需批量改机器源地址
location /ubuntu/ {
alias /data/apt-mirror/mirror/mirrors.tuna.tsinghua.edu.cn/ubuntu/;
autoindex on;
autoindex_exact_size off;
autoindex_localtime on;
}
# 原有系统ISO镜像目录完全不变,不影响装机下载镜像
location /iso/ {
alias /data/iso/;
autoindex on;
autoindex_exact_size off;
autoindex_localtime on;
}
# 大文件缓存优化,iso/deb安装包长期不变,浏览器缓存14天,减轻服务器读取压力
location ~* \.(iso|deb|gz|xz|zip|tar|sha256|whl)$ {
expires 14d;
add_header Cache-Control "public, no-transform";
}
# 禁止访问隐藏文件(数据库、日志等敏感文件)
location ~ /\. {
deny all;
}
}
EOF
