Palpo 构建指南

本文档提供了在不同平台上构建 Palpo Matrix 服务器的详细说明。

系统要求

基础要求

Rust 1.70+ (推荐使用最新稳定版)
PostgreSQL 12+
Git
Diesel CLI (可选，用于手动数据库迁移)

平台特定要求

Linux: libclang-dev, libpq-dev, cmake
macOS: Xcode Command Line Tools
Windows: Visual Studio Build Tools 2019+

macOS/Linux 构建

1. 安装依赖

macOS

# 安装 Homebrew (如果未安装)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖
brew install postgresql cmake

更多信息请参考：

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y \
    curl \
    build-essential \
    libclang-dev \
    libpq-dev \
    cmake \
    postgresql \
    postgresql-contrib

更多信息请参考：

CentOS/RHEL/Fedora

# CentOS/RHEL
sudo yum install -y gcc gcc-c++ cmake postgresql-devel clang-devel

# Fedora
sudo dnf install -y gcc gcc-c++ cmake postgresql-devel clang-devel

更多信息请参考：

2. 安装 Rust 和 Diesel CLI

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# (可选）安装 Diesel CLI (PostgreSQL 支持)
cargo install diesel_cli --no-default-features --features postgres

更多信息请参考：

3. 克隆并构建项目

# 克隆项目
git clone https://github.com/palpo/palpo.git
cd palpo

接下来：数据库配置: 数据库配置开发环境的设置：开发环境设置

Windows 构建

1. 安装依赖

使用 Chocolatey (推荐)

# 以管理员身份运行 PowerShell
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

# 安装依赖
choco install rust postgresql cmake git

更多信息请参考：

2. 安装 Diesel CLI （可选）

# 安装 Diesel CLI
cargo install diesel_cli --no-default-features --features postgres

3. 设置环境变量

# 添加到系统 PATH (根据实际安装路径调整)
$env:PATH += ";C:\Program Files\PostgreSQL\15\bin"
$env:PATH += ";C:\Program Files\CMake\bin"

4. 构建项目

# 克隆项目
git clone https://github.com/palpo/palpo.git
cd palpo

接下来：数据库配置: 数据库配置开发环境的设置：开发环境设置

5. Windows WSL 构建 (可选)

推荐在 Windows 系统中使用 WSL 环境来开发。WSL 是 Windows Subsystem for Linux，允许在 Windows 上运行 Linux 命令行工具。WSL 的安装教程可以参考官方指导： WSL 的安装和配置。

可以选择你熟悉的 Linux 发行版，如Debian 或 Ubuntu 作为 WSL 的子系统。按照上一章节中 Linux 开发配置进行配置即可。

此外，你也可使用 WSL 交叉编译构建 Windows 系统的可执行文件，参考：WSL 环境下交叉编译与安装

开发环境的设置参考：开发环境设置

数据库配置

1. 创建数据库和用户

macOS/Linux

# 启动 PostgreSQL
sudo systemctl start postgresql  # Linux
brew services start postgresql   # macOS

# 创建数据库和用户
sudo -u postgres psql -c "CREATE USER palpo_dev WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "CREATE DATABASE palpo_dev OWNER palpo_dev;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE palpo_dev TO palpo_dev;"

Windows

# 启动 PostgreSQL 服务
net start postgresql-x64-15  # 根据版本调整

# 连接数据库
psql -U postgres

在 psql 中执行

-- 创建用户
CREATE USER palpo WITH PASSWORD 'your_password';

-- 创建数据库
CREATE DATABASE palpo OWNER palpo;

-- 授予权限
GRANT ALL PRIVILEGES ON DATABASE palpo TO palpo;

-- 退出
\q

更多信息请参考：

2. 配置数据库连接

设置环境变量或创建 .env 文件：

# 方法1: 设置环境变量
export DATABASE_URL="postgres://palpo:your_password@localhost:5432/palpo"

# 方法2: 创建 .env 文件
echo "DATABASE_URL=postgres://palpo:your_password@localhost:5432/palpo" > .env

3. 运行数据库迁移(可选)

当前 Palpo 已经实现自动化迁移，无需手动执行迁移命令。如果需要手动执行迁移，请执行以下命令。

# 进入 data crate 目录
cd crates/data

# 运行迁移 (创建所有表和索引)
diesel migration run

# 验证迁移状态
diesel migration list

4. 迁移管理命令（可选）

# 查看迁移状态
diesel migration list

# 回滚最后一次迁移
diesel migration revert

# 重新运行所有迁移
diesel migration redo

# 生成新的迁移文件 (开发时使用)
diesel migration generate migration_name

更多信息请参考：

5. 验证数据库结构

连接数据库验证表是否创建成功：

psql -U palpo -d palpo -h localhost

-- 查看所有表
\dt

-- 查看表结构示例
\d users
\d rooms
\d events

-- 退出
\q

Docker 开发环境构建

1. 构建Palpo容器镜像

推荐使用 Rust 开发镜像构建 Palpo。参考配置文件：Dockerfile

FROM rust:bookworm AS builder

WORKDIR /work

RUN apt-get update && apt-get install -y --no-install-recommends \
    libclang-dev libpq-dev cmake postgresql postgresql-contrib

COPY Cargo.toml Cargo.toml
COPY crates crates
RUN cargo build --release

FROM debian:bookworm

WORKDIR /var/palpo

COPY --from=builder /work/target/release/palpo /var/palpo/palpo
# COPY crates/server/palpo-example.toml /var/palpo/palpo.toml

RUN apt-get update && apt-get install -y debian-keyring \
    debian-archive-keyring apt-transport-https ca-certificates \
    libpq-dev &&\
    mkdir -p /var/palpo/media /var/palpo/certs /var/palpo/acme

ENV PALPO_CONFIG=/var/palpo/palpo.toml
ENV RUST_LOG="palpo=warn,palpo_core=error,salvo=error"
ENV LOG_FORMAT=json

EXPOSE 8008 8448

CMD /var/palpo/palpo

将 Dockerfile 保存为 Dockerfile.palpo，单独放在某个目录下，并运行以下命令构建镜像：

docker build -t palpo-dev -f Dockerfile.palpo .

可以通过命令查看构建好的镜像：

docker images | grep palpo-dev

使用 Docker Compose 运行并测试镜像，配置可以参考：Docker Compose 配置。其中的 palpo image 配置为本地的 palpo-dev 镜像。

在启动测试前，记得要编辑配置文件：

# 编辑配置文件
cp palpo.toml.example palpo.toml
# 编辑 palpo.toml 设置你的服务器名称和数据库连接

启动服务 (包含自动数据库迁移)：docker compose up -d。

更多信息请参考：

2. Docker 环境数据库迁移（可选）

Docker 环境中的数据库迁移会自动执行，但你也可以手动运行:

# 查看迁移状态
docker compose exec palpo diesel migration list

# 手动运行迁移
docker compose exec palpo diesel migration run

# 如果需要进入容器调试
docker compose exec palpo bash

开发环境设置

1. 安装开发工具

rustfmt 是 Rust 的代码格式化工具
clippy 是代码分析工具。
cargo-watch 是 cargo 的监视工具，用于自动重载。
cargo-edit 是 cargo 的依赖管理工具，用于添加依赖。

# 安装 Rust 开发工具
rustup component add rustfmt clippy

# 安装 cargo 扩展
cargo install cargo-watch cargo-edit

更多信息请参考：

2. 设置开发数据库

# 创建开发数据库
createdb palpo_dev

# 设置开发环境变量
export DATABASE_URL="postgres://palpo:your_password@localhost:5432/palpo_dev"

# 运行迁移 (可选)
cd crates/data
diesel migration run

3. 运行开发服务器

# 复制示例配置
cp crates/server/palpo.toml palpo-dev.toml

# 编辑配置文件设置开发环境
# 修改 server_name, listen_addr, 数据库连接等

# 运行开发服务器
PALPO_CONFIG=palpo-dev.toml cargo run

# 或使用 cargo-watch 自动重载
cargo watch -x 'run'

4. 验证服务器运行

启动成功后，使用以下命令测试服务器是否正常运行：

# 检查服务器版本信息
curl http://yourservername:6006/_matrix/client/versions

# 预期返回 JSON 格式的版本信息，类似：
{
  "versions": ["r0.5.0", "r0.6.0", "v1.1", "v1.2", "v1.3", "v1.4", "v1.5", "v1.6"],
  "unstable_features": {}
}

如果返回上述 JSON 数据，说明 Palpo 服务器已成功启动并正常运行。

更多关于 Matrix API 的信息请参考：

数据库架构说明

Palpo 使用以下主要数据表：

用户相关: users, user_passwords, user_sessions, user_profiles, user_access_tokens
房间相关: rooms, room_aliases, room_tags
事件相关: events, event_datas, event_points, threads
媒体相关: media_metadatas, media_thumbnails, media_url_previews
端到端加密: e2e_device_keys, e2e_room_keys, e2e_room_keys_versions
统计相关: stats_user_daily_visits, stats_monthly_active_users, stats_room_currents
其他: threepid_*, user_pushers, server_signing_keys

所有表的详细结构可以在 crates/data/migrations/ 目录中查看。

故障排除

数据库相关问题

迁移失败:

# 检查数据库连接
psql $DATABASE_URL -c "SELECT version();"

# 检查迁移状态
diesel migration list

# 重置数据库 (谨慎使用)
dropdb palpo_dev && createdb palpo_dev
diesel migration run

权限问题:

-- 确保用户有足够权限
GRANT ALL PRIVILEGES ON DATABASE palpo TO palpo;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO palpo;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO palpo;

连接问题:

# 测试数据库连接
pg_isready -h localhost -p 5432 -U palpo

# 检查 PostgreSQL 状态
sudo systemctl status postgresql  # Linux
brew services list | grep postgres  # macOS

更多故障排除信息请参考：

常见问题

编译错误: 确保安装了所有必需的系统依赖
Diesel CLI 安装失败: 确保安装了 libpq-dev (Linux) 或 PostgreSQL 开发库
端口冲突: 修改 listen_addr 使用不同端口
权限问题: 确保 Palpo 有权限访问配置文件和媒体目录

日志调试

# 启用详细日志
RUST_LOG=debug ./target/release/palpo

# 数据库查询日志
RUST_LOG=diesel=debug ./target/release/palpo

更多调试信息请参考：

#Palpo 构建指南

#目录

#系统要求

#基础要求

#平台特定要求

#macOS/Linux 构建

#1. 安装依赖

#macOS

#Ubuntu/Debian

#CentOS/RHEL/Fedora

#2. 安装 Rust 和 Diesel CLI

#3. 克隆并构建项目

#Windows 构建

#1. 安装依赖

#使用 Chocolatey (推荐)

#2. 安装 Diesel CLI （可选）

#3. 设置环境变量

#4. 构建项目

#5. Windows WSL 构建 (可选)

#数据库配置

#1. 创建数据库和用户

#macOS/Linux

#Windows

#在 psql 中执行

#2. 配置数据库连接

#3. 运行数据库迁移(可选)

#4. 迁移管理命令（可选）

#5. 验证数据库结构

#Docker 开发环境构建

#1. 构建Palpo容器镜像

#2. Docker 环境数据库迁移（可选）

#开发环境设置

#1. 安装开发工具

#2. 设置开发数据库

#3. 运行开发服务器

#4. 验证服务器运行

#数据库架构说明

#故障排除

#数据库相关问题

#常见问题

#日志调试

Palpo 构建指南

目录

系统要求

基础要求

平台特定要求

macOS/Linux 构建

1. 安装依赖

macOS

Ubuntu/Debian

CentOS/RHEL/Fedora

2. 安装 Rust 和 Diesel CLI

3. 克隆并构建项目

Windows 构建

1. 安装依赖

使用 Chocolatey (推荐)

2. 安装 Diesel CLI （可选）

3. 设置环境变量

4. 构建项目

5. Windows WSL 构建 (可选)

数据库配置

1. 创建数据库和用户

macOS/Linux

Windows

在 psql 中执行

2. 配置数据库连接

3. 运行数据库迁移(可选)

4. 迁移管理命令（可选）

5. 验证数据库结构

Docker 开发环境构建

1. 构建Palpo容器镜像

2. Docker 环境数据库迁移（可选）

开发环境设置

1. 安装开发工具

2. 设置开发数据库

3. 运行开发服务器

4. 验证服务器运行

数据库架构说明

故障排除

数据库相关问题

常见问题

日志调试