---
title: 连接服务器与克隆项目
navTitle: 连接服务器
---
# 连接服务器与克隆项目

本文介绍 SuccApp 中服务器和项目的日常操作，包括添加服务器、登录服务器、使用服务器、设置服务器地址、浏览远端文件、克隆项目、重置项目和移除本地项目。AI 修改元数据前，应先连接测试服务器并把目标项目克隆到本地工作区。

第一次准备本地目录、Git 和推荐工作区设置时，请先阅读[初始化工作区](./init-workspace.md)。

## 基本概念{#concepts}

### 服务器{#server}

服务器是一个 SuccApp 环境，可以是测试环境、预发布环境或生产环境。SuccApp 通过服务器地址访问项目、文件、历史版本和设计器页面。

### 活跃服务器{#active-server}

一个工作区可以保存多个服务器地址，但同一时间会有一个活跃服务器。同步、克隆、推送和拉取默认针对当前活跃服务器执行。

### 项目{#project}

项目是服务器上的顶层元数据目录。克隆项目后，工作区中会出现对应目录，目录中的文件可以本地编辑、对比、推送和提交 Git。

## 添加服务器{#add-server}

打开命令面板（Windows / Linux：`Ctrl+Shift+P`；macOS：`Cmd+Shift+P`），执行 **SuccApp: 添加服务器**（英文界面为 **SuccApp: Add Server**），输入服务器地址。例如：

```text
http://localhost:8080
```

地址输入后，SuccApp 会先检查服务器地址是否可访问。地址检查通过后，SuccApp 会把服务器保存到当前工作区的 `.succapp/config.json`，并要求登录。登录成功后，该服务器会成为当前活跃服务器。

如果当前工作区还没有克隆过项目，登录成功提示中会提供 **克隆项目**（英文界面为 **Clone Projects**）按钮。点击后可以继续选择远端项目并克隆到本地。

如果添加的是已有服务器，SuccApp 会提示服务器已存在。此时可以使用服务器或登录服务器。

## 登录服务器{#login}

添加服务器时会自动进入登录流程。默认方式是 OAuth2 浏览器授权；脚本、CI、远程终端或无浏览器环境可以选择使用服务器签发的 PAT。登录成功后，SuccApp 会保存本机认证状态，后续打开工作区时会尝试自动恢复连接。

如果 OAuth2 授权失效、PAT 被撤销或服务器要求重新授权，执行 **SuccApp: 登录服务器**（英文界面为 **SuccApp: Login Server**），重新选择 OAuth2 授权或 PAT 登录。

重新认证服务器只更新认证状态，不会删除服务器配置，也不会修改本地项目文件。

## 断开连接{#disconnect}

在服务器视图中可以断开当前服务器连接，也可以执行 **SuccApp: 断开服务器连接**（英文界面为 **SuccApp: Disconnect Server**）。

断开连接只影响当前 VS Code 窗口中的连接状态，不会删除 `.succapp/config.json`，也不会删除本地已克隆项目。

## 使用服务器{#switch-server}

一个工作区可以配置多个服务器。例如，同一个项目可以同时配置测试环境和生产环境。

执行 **SuccApp: 使用服务器**（英文界面为 **SuccApp: Use Server**），选择要使用的服务器。切换后，后续克隆、拉取、推送和服务器浏览都会针对新的活跃服务器。

::: warning 注意
切换到生产服务器后，任何 push 操作都会影响生产环境。发布前必须确认 Git 版本、差异和审批流程。
:::

## 修改服务器配置{#change-server-config}

SuccApp 将服务器操作拆成独立命令，可以在命令面板中直接执行：

| 操作 | 英文界面 | 说明 |
| :--- | :--- | :--- |
| 添加服务器 | Add Server | 添加服务器地址并登录 |
| 使用服务器 | Use Server | 切换当前工作区活跃服务器 |
| 登录服务器 | Login Server | 登录当前服务器，认证失效时重新认证 |
| 设置服务器地址 | Set Server URL | 在服务器地址或端口变化时替换地址，并迁移本地服务器基线 |
| 移除服务器 | Remove Server | 从当前工作区移除服务器配置 |
| 打开服务器配置 | Open Server Config | 打开 `.succapp/config.json` 手工查看或调整 |

移除服务器配置只会从当前工作区移除该服务器地址，不会删除服务器上的项目，也不会删除本地 Git 仓库。

设置服务器地址适合服务器域名、IP 或端口变化的场景。执行前 SuccApp 会提示确认，说明该操作只会更新服务器配置并移动 `.succapp/remote/` 下的本地服务器基线，不会修改工作区中的项目文件，也不会修改服务器项目。确认后需要输入新地址并完成登录；只有登录成功且本地基线迁移成功后，SuccApp 才会写入新的服务器配置。

## 浏览服务器项目{#browse-project}

打开 SuccApp 侧边栏中的服务器视图，可以看到当前工作区配置的服务器。

连接成功后，展开服务器节点，可以看到服务器上的项目列表。项目节点通常显示项目名称和描述。

如果某个项目已经克隆到本地，服务器视图会显示相应状态。可以通过这个状态判断本地是否已经有该项目的工作副本。

## 浏览远端文件{#browse-files}

展开项目节点，可以继续浏览服务器上的远端文件和目录。

远端文件是服务器当前内容，不代表本地一定已经存在对应文件。打开远端文件时，SuccApp 会通过只读方式读取服务器内容。

远端文件常用操作包括：

1. 打开服务器源码。
2. 查看服务器文件历史。
3. 复制元数据路径。
4. 复制元数据 ID。
5. 打开服务器视图。
6. 打开服务器编辑页。

## 克隆项目到本地{#clone-project}

克隆项目是 SuccApp 将服务器元数据转换为本地文件系统的主要方式，也是 AI 低代码开发的起点。

可以通过以下入口克隆项目：

1. 执行 **SuccApp: 克隆项目**（英文界面为 **SuccApp: Clone Project**）。
2. 在服务器视图中选择项目节点，点击克隆按钮。
3. 使用 SuccApp CLI 执行 `succapp server project list` 查看当前登录可见的项目，再执行 `succapp workspace project clone <project>` 克隆指定项目。

克隆完成后，工作区根目录会出现项目目录。SuccApp 同时会在 `.succapp/remote/` 中建立该服务器项目的本地基线，用于后续差异判断。

如果新克隆的项目中包含旧版本元数据文件，SuccApp 会提示编辑前建议先升级。CLI 克隆命令只显示旧版文件总数和升级命令，不展开完整文件列表；需要先查看候选文件时，可以执行 `succapp workspace file upgrade --dry-run <project>`。省略 `<project>` 时，CLI 会预演当前 workspace 中所有本地已同步项目。克隆本身不会自动升级本地内容。

如果 CLI 提示项目不可用，通常表示项目名写错、当前账号没有权限，或当前活跃服务器不是目标服务器。先用 `succapp server project list` 确认可见项目，再使用准确的项目名重试。

::: tip 提示
首次使用某个服务器时，建议只克隆当前任务需要的项目，避免一次性下载过多无关项目。
:::

## 从服务器重置本地项目{#reset-project}

如果本地项目已经克隆过，可以在服务器视图中对已克隆项目执行 **从服务器重置本地项目**。

该操作会用服务器当前内容覆盖本地项目，本地已有修改会被放弃；如果本地存在服务器上没有的文件，也可能被删除。执行前应确认：

1. 本地未提交的修改是否已经保存或提交。
2. 当前服务器是否正确。
3. 是否真的希望放弃本地项目中的现有修改和本地新增文件。

::: warning 注意
这个操作接近于把本地项目恢复为服务器当前状态。执行前建议先查看 Git 状态，必要时先提交或备份本地修改。
:::

## 移除本地项目{#remove-project}

执行 **SuccApp: 移除本地项目**（英文界面为 **SuccApp: Remove Local Project**）可以从工作区和本地 mirror 中移除项目。

该操作只删除本地文件和本地基线，不会删除服务器项目。

如果项目已经纳入 Git，删除前应确认 Git 中是否仍需要保留这些文件。

## 多服务器使用建议{#multi-server}

测试环境和生产环境可以配置在同一个工作区中，但日常项目工作建议遵守以下规则：

1. 日常修改优先连接测试环境。
2. 生产环境只在发布窗口使用。
3. 使用服务器切换后先执行 **SuccApp: 刷新变化**（英文界面为 **SuccApp: Refresh Changes**），再查看同步状态；需要接受服务器内容时再执行 **SuccApp: 拉取变化**（英文界面为 **SuccApp: Pull Changes**）。
4. 推送生产前必须检查 Changes 视图中的差异。
5. 不要在没有 Git 记录的情况下直接覆盖生产环境。

## 常见问题{#faq}

### 登录成功后看不到项目怎么办{#no-project}

确认账号是否有访问项目的权限，并检查服务器地址是否指向正确环境。

### 克隆项目很慢怎么办{#slow-clone}

项目文件较多时，首次克隆会比较慢。建议只克隆当前任务需要的项目，并避免在网络不稳定时操作生产服务器。

### 远端文件能直接编辑吗{#remote-readonly}

服务器视图中的远端文件是只读浏览入口。需要修改文件时，应先克隆项目，在本地工作区中修改，再通过 push 同步到服务器。