Skip to content

feat: add documents for Chinese translation #1008

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions README.zh.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/OpenMinaGH_Light.svg">
<source media="(prefers-color-scheme: light)" srcset="docs/assets/OpenMinaGH_Dark.svg">
<img alt="Open Mina 节点是一个用 Rust 实现的快速且安全的 Mina 协议实现"
src="docs/assets/OpenMinaGH_Light.svg"
width="152px">
</picture>

![Beta][beta-badge] [![release-badge]][release-link] [![Changelog][changelog-badge]][changelog] [![Apache licensed]][Apache link]

_**Open Mina 节点**是一个用 **Rust** 实现的快速且安全的 Mina 协议实现。_
_目前处于**公开测试阶段**,加入我们的 [Discord 社区](https://discord.com/channels/484437221055922177/1290662938734231552)来帮助测试未来的版本。_

</div>

---

## 入门指南

### 从源码构建

- [Rust 节点](/docs/building-from-source-guide.md#how-to-build-and-launch-a-node-from-source) 和 [仪表盘](./docs/building-from-source-guide.md#how-to-launch-the-ui)

### 通过 Docker 在开发网络运行节点

- [非出块节点](/docs/alpha-testing-guide.md) 连接到对等节点并在开发网络上同步节点;无需开发网络权益。
- [出块节点](/docs/block-producer-guide.md) 在开发网络上产生区块;需要足够的开发网络权益。
- [本地出块演示](/docs/local-demo-guide.md) 在自定义本地链上产生区块,无需开发网络权益。

<img src="docs/assets/NodeUI.png" alt="区块生产节点界面">

---

## 发布流程

**本项目处于测试阶段**。我们保持每月发布周期,[每月提供更新](https://github.com/openmina/openmina/releases)。

## 核心功能

- **Mina 网络**:连接对等节点、同步、广播消息
- **区块生产**:根据 Mina 共识生产、验证和应用区块
- **SNARK 生成**:为交易生成 SNARK 证明
- **调试**:使用归档节点数据的区块重放器

## 仓库结构

- [core/](core) - 提供需要在节点不同组件之间共享的基本类型
- [ledger/](ledger) - Rust 实现的 Mina 账本
- [snark/](snark) - Snark/证明验证
- [p2p/](p2p) - OpenMina 节点的 P2p 实现
- [node/](node) - 组合节点的所有业务逻辑
- [native/](node/native) - 节点的操作系统特定部分,用于在本地运行节点(Linux/Mac/Windows)
- [testing/](node/testing) - OpenMina 节点的测试框架
- [cli/](cli) - OpenMina 命令行工具
- [frontend/](frontend) - OpenMina 前端

## Open Mina 文档

### 什么是 Open Mina?

- [为什么我们要开发 Open Mina](docs/why-openmina.zh.md)

### 核心组件

- [P2P 通信](https://github.com/openmina/openmina/blob/documentation/docs/p2p_service.md)
- [GossipSub](https://github.com/openmina/mina-wiki/blob/3ea9041e52fb2e606918f6c60bd3a32b8652f016/p2p/mina-gossip.md)
- [扫描状态](docs/scan-state.md)
- [SNARKs](docs/snark-work.md)

### 开发者工具

- [前端](./docs/building-from-source-guide.md#how-to-launch-the-ui)

### Mina 测试框架

- [完整测试文档](docs/testing/testing.md)

### 如何运行

- [非出块节点](./docs/alpha-testing-guide.md)
- [出块节点](./docs/block-producer-guide.md)
- [本地出块演示](./docs/local-demo-guide.md)

[changelog]: ./CHANGELOG.md
[beta-badge]: https://img.shields.io/badge/status-beta-yellow
[changelog-badge]: https://img.shields.io/badge/changelog-Changelog-%23E05735
[release-badge]: https://img.shields.io/github/v/release/openmina/openmina
[release-link]: https://github.com/openmina/openmina/releases/latest
[Apache licensed]: https://img.shields.io/badge/license-Apache_2.0-blue.svg
[Apache link]: https://github.com/openmina/openmina/blob/master/LICENSE
77 changes: 77 additions & 0 deletions docs/alpha-testing-guide.zh.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# 在开发网络上运行非出块节点

本指南将指导您使用 Docker 在开发网络上运行 **Alpha Rust 节点**。按照以下步骤设置节点并为这个 Alpha 版本[提供反馈](#4-提供反馈)。

## 1. 前置要求

确保您已安装 **Docker**:

- [Linux、macOS 和 Windows 的 Docker 安装指南](./docker-installation.md)

## 2. 下载并启动节点

1. **下载最新版本**:

- 访问 [Open Mina 发布页面](https://github.com/openmina/openmina/releases)
- 下载最新的 `openmina-vX.Y.Z-docker-compose.zip`

2. **解压文件**:

```bash
unzip openmina-vX.Y.Z-docker-compose.zip
cd openmina-vX.Y.Z-docker-compose
```

额外的可选参数:

`OPENMINA_LIBP2P_EXTERNAL_IP` 设置您节点的外部 IP 地址,以帮助其他节点找到它。

`OPENMINA_LIBP2P_PORT` 设置 Libp2p 通信的端口。

3. **在开发网络上启动节点并保存日志**:
启动节点并保存日志以供后续分析:

```bash
docker compose up --pull always && docker compose logs > openmina-node.log
```

4. **访问仪表板**:
在浏览器中打开 `http://localhost:8070`。

仪表板将实时显示同步过程。
<img width="1417" alt="image" src="https://github.com/user-attachments/assets/d9a5f5b3-522f-479b-9829-37402c63bb98">

> **1. 连接节点:** 节点与其他对等节点建立连接。您将看到已连接、正在连接和断开连接的节点数量增长。
>
> **2. 获取账本:** 节点下载关键数据:权益账本、下一轮账本和已验证账本。进度条显示下载状态。
>
> **3. 获取并应用区块:** 节点下载最近的区块以匹配网络的当前状态。仪表板跟踪已获取和应用的区块数量。

## 3. 监控和故障排除

### 检查保存的日志

如果您已将日志保存到文件中,可以使用 tail 或类似工具查看:

```bash
tail -f openmina-node.log
```

### 重启节点:

如果节点无响应或无法启动,请重启设置:

```bash
docker compose down
docker compose up --pull always
```

## 4. 提供反馈

此 Alpha 版本用于测试目的。您的反馈至关重要。按照以下步骤报告任何问题:

1. **收集日志**:使用[上述命令保存日志](#2-下载并启动节点)
2. **访问 Discord**:[Open Mina Discord 频道](https://discord.com/channels/484437221055922177/1290662938734231552/1290667779317305354)
3. **描述问题**:简要说明问题和重现步骤
4. **附上日志**:Discord 允许上传最大 25MB 的文件。如果您的日志更大,请使用 Google Drive 或类似服务
5. **包含截图**:仪表板截图提供了节点状态的详细信息,便于诊断问题
62 changes: 62 additions & 0 deletions docs/block-producer-guide.zh.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# 在开发网络上运行区块生产节点

本指南仅适用于在 **Mina 开发网络** 上设置区块生产节点。
在完成必要的安全审计之前,请勿将本指南用于 Mina 主网。

---

## 前置要求

确保您的系统已安装 Docker 和 Docker Compose - [Docker 安装指南](./docker-installation.zh.md)

## 下载并启动节点

1. **下载最新版本**

- 访问 [Open Mina 发布页面](https://github.com/openmina/openmina/releases)
- 下载最新的 `openmina-vX.Y.Z-docker-compose.zip`
- 解压文件:

```bash
unzip openmina-vX.Y.Z-docker-compose.zip
cd openmina-vX.Y.Z-docker-compose
mkdir openmina-workdir
```

2. **准备密钥**

[Docker Compose](../docker-compose.block-producer.yml) 引用 `openmina-workdir`。它存储区块生产所需的私钥和日志。
将您的区块生产者私钥放入 `openmina-workdir` 目录并命名为 `producer-key`:

```bash
cp /path/to/your/private_key openmina-workdir/producer-key
```

将 `/path/to/your/private_key` 替换为您私钥文件的实际路径。

3. **启动区块生产者**

使用 `MINA_PRIVKEY_PASS` 设置私钥密码。可选择使用 `COINBASE_RECEIVER` 设置不同的币基接收地址:

```bash
env COINBASE_RECEIVER="您的钱包地址" MINA_PRIVKEY_PASS="您的密码" \
docker compose -f docker-compose.block-producer.yml up -d --pull always
```

可选参数:

`OPENMINA_LIBP2P_EXTERNAL_IP` 设置您节点的外部 IP 地址,以帮助其他节点找到它。

`OPENMINA_LIBP2P_PORT` 设置 Libp2p 通信的端口。

4. **访问仪表盘**

访问 [http://localhost:8070](http://localhost:8070) 来[监控同步状态](http://localhost:8070/dashboard)和[区块生产](http://localhost:8070/block-production)。

### 访问日志

日志存储在 `openmina-workdir` 中,文件名格式如 `openmina.log.2024-10-14`、`openmina.log.2024-10-15` 等。

### 提供反馈

收集 `openmina-workdir` 中的日志,并在 [rust-node-testing](https://discord.com/channels/484437221055922177/1290662938734231552) Discord 频道报告问题。如果可能,请包含复现步骤。
100 changes: 100 additions & 0 deletions docs/building-from-source-guide.zh.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# 如何从源码构建和启动节点

本安装指南已在 Debian 和 Ubuntu 系统上测试过,应该适用于大多数 Linux 发行版。

## 前置要求

Ubuntu 或基于 Debian 的 Linux 发行版,需要安装以下软件包:

- `curl`
- `git`
- `libssl-dev`
- `pkg-config`
- `protobuf-compiler`
- `build-essential`

示例(基于 debian):

```sh
# 使用 "sudo" 或以 "root" 用户身份运行
sudo apt install curl git libssl-dev pkg-config protobuf-compiler build-essential
```

示例(macOS):

如果您尚未安装 homebrew:

```sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

```sh
brew install curl git openssl pkg-config protobuf gcc make
```

## 步骤(适用于基于 Debian 的 Linux 发行版和 macOS):

打开命令行并输入以下命令:

```sh
# 安装 rustup 并将默认 Rust 工具链设置为 1.80(更新版本也可以)
curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain 1.80
# 为当前 shell 配置 rustup
source "$HOME/.cargo/env"
# 克隆 openmina 仓库
git clone https://github.com/openmina/openmina.git
cd openmina/
# 构建并运行节点
cargo run --release -p cli node
```

# 如何启动 UI:

## 前置要求

### 1. Node.js v20.11.1

#### MacOS

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install [email protected]
```

#### Linux

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
source ~/.bashrc
nvm install 20.11.1
```

#### Windows

从官方网站下载 [Node.js v20.11.1](https://nodejs.org/),打开安装程序并按照提示完成安装。

### 2. Angular CLI v16.2.0

```bash
npm install -g @angular/[email protected]
```

### 3. 安装

打开终端并导航到项目根目录

```bash
cd PROJECT_LOCATION/openmina/frontend
```

安装依赖

```bash
npm install
```

## 运行应用

```bash
npm start
```
65 changes: 65 additions & 0 deletions docs/docker-installation.zh.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Docker 安装指南

## 适用于以下系统的安装指南

- [基于 Debian 的 Linux 系统](#基于-debian-的-linux-系统安装-docker)
- [Windows 系统](#windows-系统安装-docker)
- [macOS 系统](#macos-系统安装-docker)

## 基于 Debian 的 Linux 系统安装 Docker

1. 设置 Docker 的 apt 仓库:

```bash
# 添加 Docker 的官方 GPG 密钥:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 将仓库添加到 Apt 源:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
```

2. 安装 Docker 软件包:

```bash
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

3. 将当前用户添加到 `docker` 用户组:

```bash
sudo usermod -aG docker $USER
newgrp docker
```

4. 验证安装:

```bash
docker run hello-world
```

---

## Windows 系统安装 Docker

1. 下载并安装 [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)。

2. 确保 Docker Desktop 正在运行(检查系统托盘图标)。

---

## macOS 系统安装 Docker

1. 下载并安装 [Docker Desktop for Mac](https://www.docker.com/products/docker-desktop/)。
2. 在终端中验证安装:

```bash
docker --version
```
Loading