code-server-sync
v0.1.3
Published
经 code-server 已登录通道,在本机与云主机之间同步项目代码
Maintainers
Readme
cs-sync
cs-sync 在本机目录与运行 code-server 的云主机目录之间同步代码。
通道使用 code-server 已经登录的 /proxy/<端口>/,不另外开放公网入口。云端用 cs-sync recv 启动接收进程。
本机可以是 Windows 或 macOS。云端接收进程运行在 Linux 上。
适合谁
适合需要在本机编辑,并把代码同步到已经登录的 code-server 云主机上。
它不替代编辑器、编译器或部署流水线。
前提
本机(Windows 或 macOS):
- Node.js 18 及以上
- Python 3.9 及以上。Windows 上使用
py -3或python,macOS 上使用python3 - Git。整份同步前的暂存、行级 diff 和
sync都会用到
云端(Linux):
- Node.js 18 及以上
- Python 3.9 及以上,使用
python3 - Git。整份同步前的暂存、行级 diff 和
sync都会用到
安装
本机和云端各执行一次(在各自的终端里):
npm install -g code-server-sync
cs-sync --help
cs-sync --version不安装到全局时,在要使用的那一侧执行:
npx code-server-sync --help命令在哪执行
日常要用的 cs-sync 子命令都在本机终端执行:init、login、cookie、token、list、remove、doctor、to-cloud、to-local、diff-to-cloud、diff-to-local、sync、self-test。
只在云端 Linux 终端执行的是 cs-sync recv ...。这条命令由本机的 init 或 token 打印出来,原样粘贴到 code-server 终端。安装和升级 code-server-sync 时,本机和云端各自执行一次对应的 npm 命令。
一次完整使用会经过什么
- 在本机和云端都安装
code-server-sync - 在本机登记本机目录、云端目录和 code-server 地址
- 在本机写入 code-server 登录态
- 在本机用
token打印云端接收命令 - 把打印出的
cs-sync recv ...贴到云端终端执行 - 在本机用
doctor检查通道 - 在本机先
--dry-run,再正式同步
| 步骤 | 在哪执行 | 命令 | 结果 |
|------|----------|------|------|
| 登记 | 本机 | cs-sync init | 生成项目令牌和接收端口,并打印云端启动命令 |
| 登录 | 本机 | cs-sync login 或 cs-sync cookie | 把 code-server 登录态记到本机配置 |
| 打印命令 | 本机 | cs-sync token | 再次打印要贴到云端的 cs-sync recv ... |
| 启动接收 | 云端 | cs-sync recv ... | 云端开始在该端口接收 |
| 检查 | 本机 | cs-sync doctor | 确认代理、令牌和路径校验 |
| 演练 | 本机 | cs-sync to-cloud --dry-run | 只列出将要发生的变化 |
| 同步 | 本机 | cs-sync to-cloud 或 cs-sync sync | 按所选方式写入 |
在本机的 localRoot 目录内运行时可以省略 --name。
最短上手
下面的 init、login、token、doctor、to-cloud、sync 都在本机执行。唯一要贴到云端终端的,是 token 打印出来的那一行 cs-sync recv ...。
本机执行。 macOS(bash / zsh)用 \ 续行:
cs-sync init \
--name 我的项目 \
--local /本机/项目目录 \
--remote /云端/绝对路径 \
--base https://code-server主机:端口本机执行。 Windows PowerShell 用反引号 ` 续行,反引号必须是该行最后一个字符。--local 写本机路径:
cs-sync init `
--name 我的项目 `
--local C:\work\demo `
--remote /云端/绝对路径 `
--base https://code-server主机:端口仍在本机执行:
cs-sync login
cs-sync token --name 我的项目把 token 打印的那一行贴到云端 code-server 终端。云端执行:
cs-sync recv --root '/云端/绝对路径' --token '…' --port 27182回到本机执行:
cs-sync doctor --name 我的项目
cs-sync to-cloud --name 我的项目 --dry-run
cs-sync to-cloud --name 我的项目
cs-sync sync --name 我的项目Windows 上 --local 使用本机路径,例如 C:\work\demo。--remote 始终是云端 Linux 绝对路径。token 打印的引号按云端 shell 转义,直接粘贴到云端终端。
按意图选择命令
下面每一条都在本机执行。执行前,云端终端里要已经在跑 cs-sync recv。
我要检查通道
本机执行:
cs-sync doctor --name 我的项目我要把本机整份覆盖到云端同名路径
本机执行:
cs-sync to-cloud --name 我的项目我要把云端整份覆盖到本机同名路径
本机执行:
cs-sync to-local --name 我的项目我只想把本机尚未提交的行级改动推上去
本机执行:
cs-sync diff-to-cloud --name 我的项目我只想把云端尚未提交的行级改动拉下来
本机执行:
cs-sync diff-to-local --name 我的项目我要在保存之后双向同步启动后的增量
本机执行:
cs-sync sync --name 我的项目三种同步
to-cloud、to-local、diff-to-cloud、diff-to-local、sync 都在本机执行。云端只负责已经启动的 cs-sync recv。
整份:to-cloud / to-local
按相对路径扫描,用 SHA-256 比较内容,相同则跳过。覆盖同名文件,对端独有的文件保留。正式执行前,对即将被覆盖的一侧执行 git add -A,把当前改动放进 index。--dry-run 不会暂存。
默认同步忽略:.git、.agents、.idea、node_modules、dist、build、coverage、.next、.nuxt、.turbo、.cache、tmp、__pycache__、.venv、venv、vendor、.gradle、CMakeFiles、.dart_tool。
init 会把当时的目录名列表写入项目配置的 ignoreDirs。已经建好的项目不会自动改用新列表。要改用当前内置列表,删掉该字段;要少忽略几项,直接编辑这份列表。
扫描时会跳过约 32MB 以上的单个文件。上传和下载使用同一个大小限制,超过会拒绝。
行级:diff-to-cloud / diff-to-local
收集相对 HEAD 的 git diff,没有 HEAD 时使用已暂存内容,并包含未跟踪的新文件。对端在临时目录用 git apply 试算后再写入。合不上则跳过该文件,保留对端原内容。二进制、对端已经存在的「新增」和补丁冲突记为失败或冲突。
监视:sync
启动时扫描本机并读取云端清单,记下基线。两边当时已经不一致的内容只记基线,启动前的差异留给 to-* 或 diff-*。之后只同步启动后的保存。
本地改动按相对上次已同步内容的行级 diff 推到云端。云端改动先试行级补丁,对不上再做三路合并。真冲突时保留这一侧已有内容,并打印提示。二进制不能按行同步。
| 日志 | 含义 |
|------|------|
| 本地改动 | 本机先改,并已同步到云端。删除时带「(删除)」 |
| 本地写入 | 因为云端变更,本机文件被写入或删除 |
| 云端改动 | 云端工作区先出现变更 |
| 云端写入 | 因为本机同步,云端文件被写入或删除 |
云端日志仍是旧文案时,在云端升级 code-server-sync 并重启 cs-sync recv。本机上正在跑的 cs-sync sync 也要重新启动。
.cs-syncignore
在本机目录或云端目录放置 .cs-syncignore,语法与 gitignore 类似:*、?、**、目录尾 /、# 注释、! 否定。
它和内置忽略取并集,命中任一即跳过。! 不能抵消内置忽略,例如 !node_modules 无效。各端读取自己目录下的这份文件。扫描、整份同步、行级同步、sync 和 --dry-run 都会用它。
--dry-run
在本机加在 to-cloud、to-local、diff-to-cloud、diff-to-local、sync 后面。
不会执行 git add -A,不会调用云端暂存,不会写入或删除项目目录中的文件,不会把补丁落到工作区,也不会推送忽略规则。sync --dry-run 不进入持续监视,打印当前双边差异后退出。
会做连通检查,并只读读取云端清单。行级预览可能只读拉取对端内容,用来判断是相同跳过还是能够合入。
清单标签包括:add、modify、delete、skip-same、conflict、binary、local-only、remote-only。
命令一览
除 recv 外,下表命令都在本机终端执行。recv 只在云端 Linux 终端执行。
| 命令 | 在哪执行 | 作用 |
|------|----------|------|
| init | 本机 | 登记项目,生成令牌并分配端口 |
| list / remove | 本机 | 列出或删除映射,不删除目录里的代码 |
| login / cookie | 本机 | 写入 code-server 登录态,所有项目共用 |
| token | 本机 | 打印要贴到云端执行的 recv 启动命令 |
| doctor | 本机 | 检查代理、令牌和路径校验 |
| to-cloud | 本机 | 云端先 git add -A,再用本机文件覆盖云端同名路径 |
| to-local | 本机 | 本机先 git add -A,再用云端文件覆盖本机同名路径 |
| diff-to-cloud | 本机 | 云端先暂存,再把本机 git diff 行级推到云端;合不上则跳过 |
| diff-to-local | 本机 | 本机先暂存,再把云端 git diff 行级拉到本机 |
| sync | 本机 | 记下基线后,按行级增量与三路合并双向同步之后的保存 |
| recv | 云端 | 在云端 Linux 上接收本机发来的同步请求 |
| self-test | 本机 | 在本机临时目录检查协议,不连接真实 code-server |
同步类命令都支持 --dry-run。全局可选 --config /某/项目.json。cs-sync --version 打印当前安装的版本。
配置
默认目录是 ~/.config/cs-sync/。Windows 上是 %USERPROFILE%\.config\cs-sync。环境变量 CS_SYNC_HOME 可以改到别处。
~/.config/cs-sync/
host.json
projects/
我的项目.jsonhost.json
| 字段 | 含义 |
|------|------|
| baseUrl | code-server 根地址 |
| cookie | code-server-session=… |
| auth | 例如 password 或 none |
| insecure | 是否跳过 TLS 校验 |
projects/*.json
| 字段 | 含义 |
|------|------|
| name | 项目简称 |
| localRoot / remoteRoot | 本机目录 / 云端绝对路径 |
| port | 云端 recv 端口,默认从 27182 递增 |
| token | 项目令牌 |
| ignoreDirs | 忽略的目录名 |
配置文件按 0600 写入。Windows 上权限由系统落成它能表达的结果。项目名区分大小写。
使用时要注意
- 外网要先登录 code-server,才能到达同步接口。
- 持有项目
token才能对recv做写入。/health不校验令牌。 recv在云端监听0.0.0.0,经 code-server/proxy访问。端口不要对公网直接开放。host.json可能含登录相关字段。它不是系统钥匙串。token会出现在云端进程的命令行里,同机可以看见。- 正式同步前的暂存是
git add -A,会改动对应仓库的 index。--dry-run不会暂存。 - 常见初始化路径下,HTTPS 可能跳过证书校验。
- 单个文件超过约 32MB 时,上传和下载都会拒绝。
常见问题
| 现象 | 可能原因 | 处理 |
|------|----------|------|
| doctor 返回网页 | Cookie 失效或未登录 | 在本机重新执行 cs-sync login 或 cs-sync cookie |
| 502 / 连接被拒绝 | 云端 recv 未启动或端口不对 | 在本机再执行 cs-sync token,把打印出的命令贴到云端终端执行 |
| 403 | 本机令牌与云端 --token 不一致 | 在本机执行 cs-sync token,用打印出的命令在云端重启 recv |
| 提示接收程序过旧 | 云端的包装版本旧,缺接口 | 在云端升级 code-server-sync 并重启 cs-sync recv |
| sync 不传启动前就改过的文件 | 只跟踪启动后的增量 | 在本机改用 to-* 或 diff-*,或先看 sync --dry-run |
| 冲突后该文件本轮不动 | 同一处行变更合不上 | 人工对齐后再保存,或在本机改用整份 / 行级命令 |
| 行级大量失败 | 补丁合不上或是二进制 | 在本机改用整份同步,或先对齐内容 |
| 端口被其他程序占用 | 不是本工具的接收进程 | 在云端按提示检查该端口后手动处理 |
| sync 断网后又连上 | 监视循环接住超时和连接失败,进程不退出 | 网络恢复后下一轮自动继续,不必重启这次 sync。|
| 大文件没有出现在同步结果里,或提示「文件过大」 | 单个文件超过约 32MB(33554432 字节) | 整份扫描会跳过它,不上传也不下载。sync 打印「未同步 … :文件过大」。行级里已跟踪的这类文件按二进制跳过,未跟踪的新文件不会进入变更。写入 .cs-syncignore,或改成更小的文件 |
| 云端和本地根目录名称不同 | 登记时只分别记录两条路径,同步不比较目录名 | 按各自根目录下的相对路径对齐。本机 C:\work\demo、云端 /srv/other 时,src/app.js 仍按 src/app.js 同步。省略 --name 时,项目简称取本地目录名 |
