KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #ai #dsh-plugin #ai-agent #mcp #deepseek-harness #windows

smart-config-syncer

★ 55 Open GitHub ↗

ssync: 安全、高效的多环境配置同步器

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ⚡ ssync: 安全、高效的多环境配置同步器

[![Go Report Card](https://goreportcard.com/badge/github.com/twoKilo/smart-config-syncer)](https://goreportcard.com/report/github.com/twoKilo/smart-config-syncer)
[![Go.Dev Reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white)](https://pkg.go.dev/github.com/twoKilo/smart-config-syncer)
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/twoKilo/smart-config-syncer)](https://github.com/twoKilo/smart-config-syncer/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**`ssync`** (Smart Syncer) 是一个基于 Go 和 Cobra 框架构建的专业命令行工具，旨在解决在多项目、多环境下管理和同步配置文件的普遍痛点。它通过强大的 `age` 加密、优雅的交互界面和健壮的文件写入策略，让你的配置管理流程变得前所未有的安全与高效。

![ssync 命令演示](https://raw.githubusercontent.com/twoKilo/smart-config-syncer/main/assets/ssync.gif)

---

## 🎯 `ssync` 解决了什么问题？

在现代软件开发中，我们经常需要在不同环境（如开发、测试、生产）之间切换，每个环境都有其独立的配置，如数据库地址、API密钥等。传统方式（手动复制粘贴、使用 `.env` 文件）常常导致：

* **安全风险**：敏感信息（如 API Key, 私钥）以明文形式存储在 `.env` 文件中，容易被意外提交到 Git 仓库。
* **管理混乱**：项目一多，环境一多，配置文件散落在各处，难以维护和同步。
* **操作繁琐**：每次在新环境部署，都需要手动创建和修改配置文件，效率低下且容易出错。

`ssync` 正是为了终结这种混乱而生。

---

## ✨ 核心特性

* **🔒 端到端加密**：使用现代化的 `age` 加密库，确保敏感信息在 `config.yaml` 中以密文形式安全存储。
* **🤝 团队协作友好**：支持配置多个公钥，团队成员可以独立地添加和更新加密变量，而无需共享私钥。
* **🪄 优雅的交互体验**：基于 `bubbletea` 框架，所有核心命令（`init`, `sync`, `set`）都提供了实时、流畅的 TUI 界面，引导用户完成操作。
* **🧠 智能的 `.env` 管理**：`sync` 命令采用**区块管理**模式，只更新由 `ssync` 管理的变量区块，绝不触碰你在 `.env` 文件中添加的任何自定义内容，杜绝数据丢失风险。
* **✍️ 格式保持**：在更新 `config.yaml` 时，`ssync` 使用 `yaml.v3` 的 Node API，完美保留你原有的注释和文件布局。
* **🚀 零依赖运行**：由 Go 编译成单个二进制文件，在 Windows, macOS, Linux 上开箱即用，无需任何运行时依赖。

---

## 📦 安装

### 方式一：使用 `go install` (推荐 Go 开发者)

```bash
go install github.com/twoKilo/smart-config-syncer/cmd/smart-config-syncer@latest
```

### 方式二：从 GitHub Releases 下载 (推荐所有用户)

1.  访问项目的 **[Releases 页面](https://github.com/twoKilo/smart-config-syncer/releases)**。
2.  下载适用于你操作系统和架构的最新版本（例如 `ssync-darwin-arm64`）。
3.  解压并将二进制文件移动到你的 `PATH` 路径下。

```bash
    # 示例：将下载的文件移动并重命名为 ssync
    sudo mv ./ssync-darwin-arm64 /usr/local/bin/ssync
    ```

> **重要提示**：完成移动后，你可能需要执行以下操作之一，才能让新命令在你的终端里立即生效：
    >
    > * **选项 A (推荐)**：关闭当前的终端窗口，然后**打开一个全新的终端窗口**。
    > * **选项 B (高级)**：在当前的终端里运行 `hash -r` (适用于 Zsh, Bash)，以刷新命令路径缓存。

---

## 🛠️ 使用指南

### 1. `ssync init` - 初始化项目

在你的项目根目录下运行此命令，`ssync` 将引导你完成所有初始化设置。

```bash
ssync init
```

它会执行以下任务：
* ✅ **生成 age 密钥对**：创建公钥（用于加密）和私钥（用于解密）。
* ✅ **写入私钥文件**：将私钥保存到 `keys.txt`。（此文件应严格保密）
* ✅ **更新 .gitignore**：自动将 `keys.txt` 和 `.env` 添加到 `.gitignore`，防止敏感信息泄露。
* ✅ **创建配置文件**：生成一个 `config.yaml` 样板文件，其中已包含你的公钥。

### 2. `ssync set` - 安全地设置变量

这是**最常用**的命令之一。用它来添加或更新配置，告别手动编辑 YAML 和加密。

```bash
# 设置一个普通变量
ssync set my-first-project.development DB_USER admin

# 使用 -e 或 --encrypt 标志来加密一个敏感值
ssync set my-first-project.production API_KEY "your-super-secret-key" --encrypt
```

**参数说明:**
* **`<project.env>`**: 目标路径，格式为 `项目名.环境名`，与 `config.yaml` 中定义的结构对应。
* **`<key>`**: 变量名。
* **`<value>`**: 变量值。
* **`--encrypt, -e`**: (可选) 是否在存入前对 `<value>` 进行加密。

### 3. `ssync sync` - 同步配置到 `.env`

当你想将某个环境的配置应用到当前目录时，运行此命令。

```bash
# 将 my-first-project 的 production 环境配置同步到 .env 文件
ssync sync my-first-project.production
```

`ssync` 会：
1.  找到并读取 `config.yaml`。
2.  加载 `keys.txt` 中的私钥。
3.  解密 `production` 环境下的所有加密变量 (以 `ENC[...]` 开头的)。
4.  将所有解密后的键值对写入当前目录的 `.env` 文件中一个被特殊标记的区块内。

生成的 `.env` 文件会是这样：

```dotenv
# 用户自定义的变量，ssync 绝不会动它
MY_LOCAL_VAR=some_value

# BEGIN SSYNC MANAGED BLOCK
LOG_LEVEL=info
DB_HOST=prod.db.server.com
API_KEY=your-super-secret-key
# END SSYNC MANAGED BLOCK
```

---

## ⚙️ `config.yaml` 文件结构

`ssync` 的所有配置都围绕 `config.yaml` 文件。

```yaml
# ssync 工具的配置文件
ssync_version: "1.0"

# 负责加密的公钥列表。
# `ssync set --encrypt` 会使用这里的公钥。
# 你可以添加团队中其他成员的公钥，这样他们也能添加新的加密变量。
public_keys:
  - "age1..." # 你的公钥
  - "age1..." # 团队成员A的公钥

# -------------------------------------------------------------------
# 项目配置区
# -------------------------------------------------------------------
projects:
  # 你的第一个项目，例如一个Web后端服务
  my-backend-service:
    # 开发环境配置
    development:
      LOG_LEVEL: "debug"
      DB_HOST: "localhost"
      DB_PORT: "5432"
      API_URL: "http://dev.api.example.com"

# 生产环境配置
    production:
      LOG_LEVEL: "info"
      DB_HOST: "prod.db.server.com"
      DB_PORT: "5432"
      # 使用 ssync set --encrypt 添加的加密变量
      DATABASE_URL: "ENC[...your_encrypted_db_connection_string...]"

# 你的第二个项目，例如一个数据处理管道
  my-data-pipeline:
    # 开发环境配置
    development:
      S3_BUCKET: "dev-bucket"
      WORKER_COUNT: "2"
      # 对于不需要加密的普通变量，直接写明文即可
      KAFKA_BROKER: "kafka-dev:9092"

# 生产环境配置
    production:
      S3_BUCKET: "prod-data-lake-bucket-12345"
      WORKER_COUNT: "10"
      KAFKA_BROKER: "kafka-prod-1.example.com:9092,kafka-prod-2.example.com:9092"
      # 对于需要加密的敏感变量，使用 ssync set --encrypt 命令添加
      AWS_SECRET_ACCESS_KEY: "ENC[...your_encrypted_aws_secret...]"
```

---

## ❤️ 贡献

欢迎任何形式的贡献！如果你有好的想法、发现了 Bug，或者想改进某个功能，请随时提交 Pull Request 或创建 Issue。

## 📜 许可证

本项目基于 **[MIT License](https://opensource.org/licenses/MIT)** 开源。

smart-config-syncer

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README