> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorose.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 开发环境搭建

> 按当前仓库结构和脚本搭建本地 Memorose 开发环境。

# 开发环境搭建

## 前置条件

| 工具                | 版本    | 备注                         |
| ----------------- | ----- | -------------------------- |
| Rust              | 1.88+ | 由仓库根目录 `rust-toolchain` 固定 |
| Node.js           | 20+   | 用于 dashboard 前端            |
| pnpm              | 最新版   | dashboard 包管理器             |
| protobuf-compiler | —     | Raft 相关构建步骤需要              |
| cmake             | —     | 某些原生依赖需要                   |
| libclang-dev      | —     | Linux 上 `bindgen` 需要       |

### macOS

```bash theme={null}
brew install protobuf cmake node
npm i -g pnpm
rustup install 1.88.0
```

### Ubuntu / Debian

```bash theme={null}
sudo apt install -y protobuf-compiler cmake libclang-dev
npm i -g pnpm
rustup install 1.88.0
```

## 克隆与构建

```bash theme={null}
git clone https://github.com/ai-akashic/Memorose.git
cd Memorose
cargo build
```

工作区包含四个 crate：`memorose-common`、`memorose-core`、`memorose-server` 和 `memorose-gateway`。

构建 dashboard：

```bash theme={null}
cd dashboard
pnpm install
pnpm build
```

## 配置

复制示例环境文件：

```bash theme={null}
cp .env.example .env
```

至少设置一个 provider key 和模型名：

```bash theme={null}
GOOGLE_API_KEY=your_key_here
LLM_MODEL=gemini-2.0-flash
EMBEDDING_MODEL=text-embedding-004
```

如果你想通过环境变量明确指定 provider，优先使用：

```bash theme={null}
MEMOROSE__LLM__PROVIDER=Gemini
```

或者：

```bash theme={null}
MEMOROSE__LLM__PROVIDER=OpenAI
OPENAI_API_KEY=your_key_here
```

请根据 `crates/memorose-common/src/config.rs` 的当前 schema 手工创建 `config.toml`。不要把 `config.example.toml` 当成完全最新的模板。

## 本地运行

### Standalone 模式

最快拿到单节点实例的方式：

```bash theme={null}
./scripts/start_cluster.sh start --mode standalone
```

这会在 `3000` 启动一个 API 节点，在 `3100` 启动 dashboard。

### 本地 Cluster 模式

模拟 3 节点本地 Raft 集群：

```bash theme={null}
./scripts/start_cluster.sh start --clean --build
```

### 其他辅助命令

```bash theme={null}
./scripts/start_cluster.sh status
./scripts/start_cluster.sh stop
./scripts/start_cluster.sh restart --clean
```

### Dashboard 开发服务器

用于前端热更新开发：

```bash theme={null}
cd dashboard
pnpm dev
```

## 端口

| 服务          | 端口        | 备注                        |
| ----------- | --------- | ------------------------- |
| API（node 1） | 3000      | 主本地节点                     |
| API（node 2） | 3001      | 仅本地 cluster 模式            |
| API（node 3） | 3002      | 仅本地 cluster 模式            |
| Gateway     | 8080      | 仅 `docker-compose.yml` 场景 |
| Dashboard   | 3100      | Next.js 前端                |
| Raft        | 5001–5003 | 内部共识流量                    |

## Docker

仓库提供了 `docker-compose.yml`：

```bash theme={null}
docker compose up
```

这会启动 gateway、两个 server 节点和 dashboard。

<Note>
  在 Docker 里运行 dashboard 时，请把 `DASHBOARD_API_ORIGIN` 指向后端容器 URL，例如 `http://memorose-node-0:3000`。否则 dashboard 会在自己的容器里请求 `127.0.0.1:3000` 并失败。
</Note>