# 配置同步/服务端

本文说明 `cdxs` 当前配置同步和同步服务端功能的实现方式、调用机制和运行过程。

## 功能范围

配置同步/服务端主要覆盖以下能力：

- 启动一个最小 HTTP 同步服务。
- 在服务端配置文件中添加或更新登录用户。
- 客户端使用用户名和密码登录同步服务。
- 客户端把本地可移植配置推送到服务端。
- 客户端从服务端拉取可移植配置并覆盖本地状态。
- 查看当前客户端同步配置状态。
- 使用 Docker 或 docker-compose 运行同步服务。

当前同步的数据只包含 `cdxs.toml` 中的可移植状态：

- `meta`
- `accounts`
- `homes`

不会同步客户端本地的 `sync` 配置，也不会把服务端的 `server.users`、`server.sessions` 下发给客户端。

## 核心文件

- `src/main.rs`：CLI 入口，负责把 `server` 和 `sync` 命令分发到具体模块。
- `src/cli.rs`：定义同步服务端和客户端命令参数。
- `src/server.rs`：HTTP 同步服务端实现，包含用户管理、登录、鉴权、状态读写。
- `src/sync_client.rs`：客户端同步逻辑，包含登录、拉取、推送和状态查看。
- `src/config_store.rs`：`cdxs.toml` 数据模型、加载、保存和默认 home 初始化。
- `Dockerfile`：构建并运行 `cdxs server run` 的容器镜像。
- `docker-compose.yml`：使用具名 volume 持久化 `/data/cdxs.toml` 并暴露 `8765` 端口。

## 数据保存方式

同步功能复用 `Store` 结构，也就是 `cdxs.toml` 的配置模型。

客户端默认读取当前 `CODEX_HOME` 下的配置：

```text
<CODEX_HOME>\cdxs.toml
```

如果没有设置 `CODEX_HOME`，默认使用：

```text
%USERPROFILE%\.codex\cdxs.toml
```

服务端有两种数据路径：

- 如果 `server run --data <路径>` 被指定，服务端直接使用这个路径保存数据。
- 如果未指定 `--data`，服务端使用当前 `CODEX_HOME` 下的 `cdxs.toml`。

`server user add` 也使用同一套路径规则，因此添加用户和启动服务必须指向同一个数据文件，才能让服务端读取到该用户。

## Store 中的相关字段

`Store` 中和同步相关的字段包括：

- `meta`：当前账号、当前 home 等元数据。
- `accounts`：账号列表。
- `homes`：受管理的 `CODEX_HOME` 列表。
- `server`：服务端用户和 bearer session，仅服务端使用。
- `sync`：客户端保存的服务端地址、用户名、token、最近拉取/推送时间。

服务端用户保存在：

```text
Store.server.users
```

服务端登录 session 保存在：

```text
Store.server.sessions
```

客户端同步配置保存在：

```text
Store.sync
```

## 服务端用户与 Token 原理

添加用户时，`server::add_user` 会生成随机 salt，并把密码保存为哈希值。

密码哈希方式：

```text
sha256(salt + ":" + password)
```

登录成功后，服务端生成一个随机 bearer token，并只保存 token 的哈希值。

token 哈希方式：

```text
sha256("cdxs-token:" + token)
```

原始 token 只在 `/v1/login` 响应中返回一次，由客户端保存到本地 `Store.sync.token`。后续 `pull` 和 `push` 使用：

```http
Authorization: Bearer <token>
```

服务端收到请求后，对请求中的 token 重新计算哈希，并检查是否存在于 `Store.server.sessions`。

```mermaid
flowchart TD
    A[server user add] --> B[生成 salt]
    B --> C[计算 password_hash]
    C --> D[写入 Store.server.users]
    E[sync login] --> F[校验 username/password]
    F --> G[生成 bearer token]
    G --> H[保存 token_hash 到 Store.server.sessions]
    H --> I[原始 token 返回给客户端]
    J[sync pull/push] --> K[Authorization Bearer token]
    K --> L[服务端计算 token_hash]
    L --> M{sessions 中是否存在}
    M -->|是| N[允许访问 /v1/state]
    M -->|否| O[返回 401]
```

## HTTP API

同步服务端使用 `axum` 提供三个接口：

- `GET /health`：健康检查，返回 `ok`。
- `POST /v1/login`：使用用户名和密码登录，返回 bearer token。
- `GET /v1/state`：鉴权后返回服务端保存的可移植状态。
- `PUT /v1/state`：鉴权后用客户端提交的可移植状态替换服务端状态。

`/v1/state` 的读写都会经过 `authorize` 鉴权。

服务端返回给客户端前会调用 `sanitized_for_client`，把以下字段清空：

- `server`
- `sync`

这样客户端不会拿到服务端用户、密码哈希、已签发 session，也不会拿到服务端自己的同步配置。

## 命令调用机制

同步相关命令由 `src/cli.rs` 定义，再由 `src/main.rs` 分发。

```mermaid
flowchart TD
    A[用户执行 cdxs 命令] --> B[Cli::parse]
    B --> C[src/main.rs match Commands]
    C --> D{命令类型}
    D -->|cdxs server run| E[server::run_server]
    D -->|cdxs server user add| F[server::add_user]
    D -->|cdxs sync login| G[sync_client::login]
    D -->|cdxs sync pull| H[sync_client::pull]
    D -->|cdxs sync push| I[sync_client::push]
    D -->|cdxs sync status| J[sync_client::status]
```

## 添加服务端用户运行过程

命令：

```powershell
cdxs server user add <username> --password <password>
```

可选指定服务端数据文件：

```powershell
cdxs server user add <username> --password <password> --data <cdxs.toml路径>
```

运行过程：

1. 调用 `resolve_data_path` 解析服务端数据文件路径。
2. 调用 `Store::load_from_path` 加载服务端 `cdxs.toml`，文件不存在时生成默认 store。
3. 校验用户名和密码不能为空。
4. 生成随机 salt。
5. 使用 salt 和密码计算 `password_hash`。
6. 如果用户已存在，替换原用户记录。
7. 如果用户不存在，追加到 `Store.server.users`。
8. 调用 `Store::save_to_path` 保存服务端配置。

```mermaid
sequenceDiagram
    participant U as 用户
    participant M as main.rs
    participant S as server.rs
    participant C as config_store.rs

    U->>M: cdxs server user add alice --password ***
    M->>S: add_user(data, username, password)
    S->>S: resolve_data_path
    S->>C: Store::load_from_path
    C-->>S: Store
    S->>S: random_token 生成 salt
    S->>S: hash_secret
    S->>S: upsert ServerUser
    S->>C: save_to_path
    C-->>U: 用户已添加/更新
```

## 启动服务端运行过程

命令：

```powershell
cdxs server run
```

默认监听：

```text
127.0.0.1:8765
```

可选参数：

```powershell
cdxs server run --bind 0.0.0.0:8765
cdxs server run --data <cdxs.toml路径>
```

运行过程：

1. 调用 `resolve_data_path` 解析服务端数据文件和默认 home。
2. 解析 `--bind` 为 `SocketAddr`。
3. 创建 `AppState`，保存数据路径、默认 home 和一个异步 `Mutex`。
4. 注册 `/health`、`/v1/login`、`/v1/state` 路由。
5. 绑定 TCP listener。
6. 调用 `axum::serve` 持续处理请求。

服务端在每个会读写配置文件的请求中都会先获取 `AppState.lock`。这个锁用于串行化文件读写，避免并发请求同时读写同一个 `cdxs.toml`。

```mermaid
flowchart TD
    A[cdxs server run] --> B[resolve_data_path]
    B --> C[解析 bind 地址]
    C --> D[创建 AppState]
    D --> E[注册 axum Router]
    E --> F[绑定 TcpListener]
    F --> G[axum::serve]
    G --> H[处理 /health /v1/login /v1/state]
```

## 客户端登录运行过程

命令：

```powershell
cdxs sync login --server http://127.0.0.1:8765 --user alice --password <password>
```

运行过程：

1. 客户端规范化 server URL，去掉末尾 `/`。
2. 向 `<server>/v1/login` 发送 JSON 请求。
3. 服务端加载 `cdxs.toml`。
4. 服务端按用户名查找 `Store.server.users`。
5. 服务端校验密码哈希。
6. 登录成功后生成 bearer token。
7. 服务端保存 token 哈希到 `Store.server.sessions`。
8. 客户端解析响应中的原始 token。
9. 客户端加载本地 `cdxs.toml`。
10. 客户端写入 `Store.sync.server_url`、`Store.sync.username`、`Store.sync.token`。
11. 客户端保存本地配置。

```mermaid
sequenceDiagram
    participant U as 用户
    participant C as sync_client.rs
    participant H as HTTP
    participant S as server.rs
    participant FS as cdxs.toml

    U->>C: cdxs sync login
    C->>H: POST /v1/login username/password
    H->>S: login_handler
    S->>FS: 加载服务端 Store
    S->>S: 校验 password_hash
    S->>S: 生成 bearer token 并保存 token_hash
    S->>FS: 保存服务端 Store
    S-->>C: token
    C->>FS: 加载本地 Store
    C->>FS: 保存 sync.server_url / username / token
    C-->>U: sync login 成功
```

## 拉取配置运行过程

命令：

```powershell
cdxs sync pull
```

运行过程：

1. 加载本地 `cdxs.toml`。
2. 从 `Store.sync` 读取 server URL 和 token。
3. 如果未登录或缺少 token，返回错误。
4. 向 `<server>/v1/state` 发送 `GET` 请求，并附带 `Authorization` header。
5. 服务端校验 bearer token。
6. 服务端加载服务端 `Store`。
7. 服务端清空 `server` 和 `sync` 字段后返回 JSON。
8. 客户端解析远端 `Store`。
9. 客户端用远端 `meta`、`accounts`、`homes` 覆盖本地对应字段。
10. 客户端保留本地 `sync` 配置，并更新 `last_pull_at`。
11. 保存本地 `cdxs.toml`。

```mermaid
flowchart TD
    A[cdxs sync pull] --> B[加载本地 Store]
    B --> C[sync_endpoint 读取 server/token]
    C --> D[GET /v1/state]
    D --> E[服务端 authorize]
    E --> F[服务端 sanitized_for_client]
    F --> G[返回远端 Store]
    G --> H[覆盖本地 meta/accounts/homes]
    H --> I[更新 last_pull_at]
    I --> J[保存本地 cdxs.toml]
```

## 推送配置运行过程

命令：

```powershell
cdxs sync push
```

运行过程：

1. 加载本地 `cdxs.toml`。
2. 从 `Store.sync` 读取 server URL 和 token。
3. 克隆本地 `Store` 作为上传 payload。
4. 上传前把 payload 中的 `server` 和 `sync` 字段清空。
5. 向 `<server>/v1/state` 发送 `PUT` 请求，并附带 `Authorization` header。
6. 服务端校验 bearer token。
7. 服务端加载原服务端 `Store`。
8. 服务端只用 payload 中的 `meta`、`accounts`、`homes` 替换服务端状态。
9. 服务端把 `sync` 置为默认值，保留原服务端的 `server.users` 和 `server.sessions`。
10. 服务端保存配置。
11. 客户端更新本地 `last_push_at`。
12. 客户端保存本地 `cdxs.toml`。

```mermaid
sequenceDiagram
    participant C as sync_client.rs
    participant S as server.rs
    participant FS as cdxs.toml

    C->>FS: 加载本地 Store
    C->>C: payload.server/default, payload.sync/default
    C->>S: PUT /v1/state + Bearer token
    S->>FS: 加载服务端 Store
    S->>S: authorize
    S->>S: 替换 meta/accounts/homes
    S->>FS: 保存服务端 Store
    S-->>C: sanitized Store
    C->>FS: 更新 last_push_at 并保存
```

## 查看同步状态

命令：

```powershell
cdxs sync status
```

输出内容来自本地 `Store.sync`：

- `server`
- `user`
- `token`
- `last_pull_at`
- `last_push_at`

如果本地保存了 token，输出只显示：

```text
<stored>
```

不会打印 token 明文。

## Docker 运行方式

`Dockerfile` 使用两阶段构建：

1. 使用 `rust:1-bookworm` 构建 release 版本 `cdxs`。
2. 使用 `debian:bookworm-slim` 作为运行镜像。
3. 安装 `ca-certificates`。
4. 把 `cdxs` 复制到 `/usr/local/bin/cdxs`。
5. 暴露 `8765` 端口。
6. 声明 `/data` volume。

容器默认命令：

```text
cdxs server run --bind 0.0.0.0:8765 --data /data/cdxs.toml
```

`docker-compose.yml` 会：

- 构建当前目录镜像。
- 将容器命名为 `cdxs-server`。
- 设置 `restart: unless-stopped`。
- 映射宿主机 `8765` 到容器 `8765`。
- 使用具名 volume `cdxs-data` 挂载到 `/data`。

## 写入安全机制

服务端和客户端保存 `cdxs.toml` 都调用 `Store::save` 或 `Store::save_to_path`。

保存时会：

1. 如果目标文件已存在，先备份到对应 home 下的 `cdxs-backups`。
2. 将 `Store` 序列化为 TOML。
3. 写入同目录临时文件。
4. 使用 rename 替换目标文件。

服务端请求还会使用 `tokio::sync::Mutex` 串行化文件读写，降低并发请求导致状态覆盖或文件损坏的风险。

## 当前实现边界

- 同步没有字段级合并或冲突解决，`pull` 会用远端 `meta/accounts/homes` 覆盖本地，`push` 会用本地 `meta/accounts/homes` 覆盖服务端。
- bearer session 当前没有过期时间和撤销命令。
- 服务端用户只有添加/更新命令，没有删除、列表或改密命令。
- 服务端没有多租户隔离；所有通过鉴权的用户访问同一份服务端状态。
- HTTP 服务没有在代码中直接配置 TLS，需要由外部反向代理或部署环境处理。
- `sync push` 不上传客户端本地 `sync` token，也不上传客户端本地 `server` 配置。
- `sync pull` 不会写入远端 `server` 或远端 `sync` 字段，只更新本地可移植状态并保留本地同步登录信息。