一、为什么你需要 AppSync？
如果你用 1Panel 管理 2 台以上的服务器，大概率已经添加过第三方应用商店（比如 okxlin/appstore）来扩充可用应用。但维护起来有两个痛点：
- 商店更新频繁：第三方仓库可能在数小时内就更迭多个应用版本，不更新就跟不上节奏。
- 手动操作重复且无聊：每次更新都要 SSH 到每台机器执行
1panel appstore sync或手动拉取，一旦遗漏就会导致环境不一致。
1Panel 从 v2.0.17 起支持多主机部署，可以把应用批量装到各节点，但它没有解决应用商店本身的自动同步问题——仓库元数据仍然要你自己去拉取。
1Panel AppSync 就是填补这个空白的小工具。它像一个忠实的后台管家，自动从 Git 拉取第三方商店的最新应用定义，写到 1Panel 的本地目录中。你完全不用再惦记“商店是不是又更新了”，所有节点随时保持应用列表一致。
二、AppSync 是怎么工作的？
原理非常简单，把它想象成一个“自动下载器”：
你指定的 Git 仓库（例如 okxlin/appstore）
│
│ 每 10 分钟自动 git pull
▼
1panel-appsync (daemon 模式)
│
│ 写入
▼
1Panel 本地应用目录（/opt/1panel/resource/apps/local/）
│
│ 1Panel 读取
▼
1Panel 网页端「应用商店」几个关键点要记住：
- 不依赖 cron：AppSync 内部自带定时器，默认每 10 分钟自动同步一次。
- Git 全量覆盖：直接从 GitHub 或 CNB（国内镜像）拉取仓库文件，同步到本地的
apps/local目录。 - 自动备份：每次同步前会备份现有数据到
/var/lib/1panel-appsync/backups/，出现异常可以一键回滚。
三、准备条件
开始安装前，确保你的环境满足：
- 已安装 1Panel 面板（社区版或专业版均可）
- 服务器能访问 GitHub（网络不佳也没关系，AppSync 支持国内 CNB 节点）
- 拥有 root 或 sudo 权限
- Linux 系统：
amd64/arm64架构均可
四、一条命令安装
4.1 标准安装（推荐）
SSH 连接到服务器，执行：
curl -fsSL https://raw.githubusercontent.com/mengfox/1panel-appsync-release/main/install-update.sh | sudo bash这个命令会自动完成：
- 下载最新版二进制文件到
/usr/local/bin/ - 探测 1Panel 的本地应用目录
- 立即执行一次同步（安装完就能看到效果）
- 创建 systemd 服务
1panel-appsync.service - 开启开机自启
- 启动 daemon 模式，后续每 10 分钟自动同步
安装结束时终端会输出程序版本、服务状态等摘要信息。
4.2 国内网络加速
如果服务器访问 GitHub 不稳定，使用 CNB 国内镜像：
curl -fsSL https://cnb.cool/mengfox/1panel-appsync-release/-/git/raw/main/install-update.sh | sudo bash注意：CNB 的 Raw 地址必须是 /-/git/raw/main/ 格式，不能写成 /-/raw/main/。
4.3 高级安装选项
通过环境变量可以精细控制安装行为，下面是几个常见场景。
① 只想装程序，不立即同步
curl -fsSL ... | sudo env SYNC_AFTER_INSTALL=false bash② 1Panel 应用目录不在默认位置
curl -fsSL ... | sudo env APPSYNC_DAEMON_ARGS="--local-dir /data/1panel/resource/apps/local" bash③ 强制使用国内节点
curl -fsSL ... | sudo env REGION_MODE=cn bash④ 安装指定版本
curl -fsSL ... | sudo env CHANNEL=v0.5.0 bash此时会从 GitHub Release 精确拉取对应版本。
⑤ 只安装二进制，不创建 systemd 服务
curl -fsSL ... | sudo env INSTALL_SERVICE=false bash全部可用环境变量速查：
| 变量 | 默认值 | 作用 |
|---|---|---|
REGION_MODE | auto | 节点选择：auto（自动测速）/ cn（强制 CNB）/ global（强制 GitHub） |
SYNC_AFTER_INSTALL | true | 安装后是否立即同步一次 |
APPSYNC_DAEMON_ARGS | 空 | 传递给 daemon 的额外参数，例如自定义应用目录 |
INSTALL_SERVICE | true | 是否写入 systemd 服务文件 |
ENABLE_SERVICE | true | 是否设为开机自启 |
START_SERVICE | true | 是否安装后立刻启动服务 |
INSTALL_DEPS | true | 是否自动安装依赖 |
RUN_DETECT | true | 是否自动探测 1Panel 本地应用目录 |
CHANNEL | latest | 安装的版本号 |
五、验证是否安装成功
用下面几条命令快速检查：
# 查看版本
1panel-appsync version
# 显示程序和服务状态
1panel-appsync status
# 查看 systemd 服务日志
systemctl status 1panel-appsync.service如果服务处于 active (running) 状态，恭喜你，自动同步已经在后台运行了。
六、日常使用命令一览
AppSync 提供了一组清晰的子命令，所有操作都可以在终端完成。
| 命令 | 说明 |
|---|---|
1panel-appsync version | 查看版本 |
1panel-appsync doctor | 全面诊断（依赖、网络、目录等） |
1panel-appsync deps --install | 安装/检查运行所需的系统依赖 |
1panel-appsync detect | 自动检测 1Panel 的本地应用目录 |
1panel-appsync check | 检查远程仓库是否有更新 |
1panel-appsync source | 查看当前同步源（Git 地址、分支等） |
1panel-appsync sync --dry-run | 模拟同步，只展示变动不实际写入 |
1panel-appsync sync | 立即手动执行一次同步 |
1panel-appsync status | 查看最近一次同步结果和时间 |
1panel-appsync rollback | 回滚到上一次备份（同步前自动备份） |
七、自定义 1Panel 目录与持久化配置
如果你的 1Panel 安装时修改了默认路径（比如 /opt/1panel 变成了 /data/1panel），需要让 AppSync 知道正确位置。
临时手动执行：
1panel-appsync sync --local-dir /data/1panel/resource/apps/local让 daemon 模式也长期使用该路径：
sudo nano /etc/1panel-appsync/env添加或修改：
APPSYNC_DAEMON_ARGS="--local-dir /data/1panel/resource/apps/local"然后重启服务：
sudo systemctl restart 1panel-appsync.service注意：--local-dir 必须以 resource/apps/local 或 apps/local 结尾，否则会报错。
八、运维与排障
8.1 服务管理
# 查看实时日志
journalctl -u 1panel-appsync.service -f
# 重启
sudo systemctl restart 1panel-appsync.service
# 手动启用并立即启动
sudo systemctl enable --now 1panel-appsync.service8.2 备份与回滚
每次自动或手动同步前，AppSync 都会在 /var/lib/1panel-appsync/backups/ 生成一份当前应用的备份。如果同步后发现应用列表异常，可以随时回滚：
1panel-appsync rollback8.3 更新到最新版
保持工具最新，只需重新执行安装脚本并指定 update：
# GitHub 渠道
curl -fsSL https://raw.githubusercontent.com/mengfox/1panel-appsync-release/main/install-update.sh | sudo bash -s update
# CNB 国内
curl -fsSL https://cnb.cool/mengfox/1panel-appsync-release/-/git/raw/main/install-update.sh | sudo bash -s update升级过程会保留原有配置，不用重新设置环境变量或目录。
8.4 自检诊断
当同步好像“不工作”时，先跑一遍诊断：
1panel-appsync doctor它会检查：二进制完整性、运行依赖、1Panel 本地目录是否存在、Git 网络是否通、配置文件格式等，通常能帮你快速定位问题。
九、彻底卸载
如果将来不需要 AppSync 了，一键卸载：
# GitHub
curl -fsSL https://raw.githubusercontent.com/mengfox/1panel-appsync-release/main/install-update.sh | sudo bash -s uninstall
# CNB
curl -fsSL https://cnb.cool/mengfox/1panel-appsync-release/-/git/raw/main/install-update.sh | sudo bash -s uninstall卸载默认保留配置目录
/etc/1panel-appsync、备份数据/var/lib/1panel-appsync和日志/var/log/1panel-appsync，以便日后恢复。如需彻底清理，手动删除这些目录即可。
十、常见问题与答案
Q1：安装后服务没起来怎么办？
手动处理：
sudo systemctl enable --now 1panel-appsync.service
systemctl status 1panel-appsync.service # 确认 runningQ2：日志显示网络超时或 git 无法拉取？
先 1panel-appsync doctor 检查。如果 GitHub 不通，可以强制使用 CNB 节点重新安装，或者修改库源配置。
Q3：怎么跳过安装时的即刻同步？
加上环境变量：
curl ... | sudo env SYNC_AFTER_INSTALL=false bashQ4：我的 1Panel 应用目录不在 /opt 怎么办？
安装后编辑 /etc/1panel-appsync/env，添加 APPSYNC_DAEMON_ARGS="--local-dir <你的路径>"，然后重启服务。
Q5：同步频率可以改成每 5 分钟吗？
当前内置调度器固定为 10 分钟，暂不支持修改。如果你需要自定义频率，可以停用 daemon 模式，改用 1panel-appsync sync 配合你喜欢的 crontab 任务。
Q6：1Panel V2 本身就能多节点部署应用，还需要 AppSync 吗？
需要，而且两者是“黄金搭档”。1Panel V2 的多主机部署是应用安装层的同步，AppSync 是应用商店元数据层的同步。只有商店元数据一致，多主机部署时才能确保选到的应用版本、配置完全统一。
十一、获取帮助与提交适配需求
AppSync 对上架于第三方商店的大多数应用都能无缝同步。如果你遇到了个别应用同步后显示异常，或者有新的应用商店适配需求，欢迎去官方论坛提交反馈：
👉 https://www.mengfox.com/forums
在那里你可以：
- 报告同步出现问题的大致现象与日志
- 提出希望支持的新应用商店或特殊仓库结构
- 和其他 1Panel、AppSync 用户交流最佳实践
开发者会定期查看论坛帖子，并根据反馈优化同步兼容性。你的每一个需求都可能让工具变得更好用。
暂无评论内容