开发环境搭建

前置条件

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

macOS

brew install protobuf cmake node
npm i -g pnpm
rustup install 1.88.0

Ubuntu / Debian

sudo apt install -y protobuf-compiler cmake libclang-dev
npm i -g pnpm
rustup install 1.88.0

克隆与构建

git clone https://github.com/ai-akashic/Memorose.git
cd Memorose
cargo build

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

cd dashboard
pnpm install
pnpm build

配置

复制示例环境文件：

cp .env.example .env

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

GOOGLE_API_KEY=your_key_here
LLM_MODEL=gemini-2.0-flash
EMBEDDING_MODEL=text-embedding-004

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

MEMOROSE__LLM__PROVIDER=Gemini

或者：

MEMOROSE__LLM__PROVIDER=OpenAI
OPENAI_API_KEY=your_key_here

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

本地运行

Standalone 模式

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

./scripts/start_cluster.sh start --mode standalone

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

本地 Cluster 模式

模拟 3 节点本地 Raft 集群：

./scripts/start_cluster.sh start --clean --build

其他辅助命令

./scripts/start_cluster.sh status
./scripts/start_cluster.sh stop
./scripts/start_cluster.sh restart --clean

Dashboard 开发服务器

用于前端热更新开发：

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：

docker compose up

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

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

​开发环境搭建

​前置条件

​macOS

​Ubuntu / Debian

​克隆与构建

​配置

​本地运行

​Standalone 模式

​本地 Cluster 模式

​其他辅助命令

​Dashboard 开发服务器

​端口

​Docker

开发环境搭建

前置条件

macOS

Ubuntu / Debian

克隆与构建

配置

本地运行

Standalone 模式

本地 Cluster 模式

其他辅助命令

Dashboard 开发服务器

端口

Docker