使用指南
资助项目
使用指南
资助项目
简体中文

Palpo 构建指南

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

目录

系统要求

基础要求

平台特定要求

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

# 构建项目
cargo build --release

# 构建完成后，可执行文件位于
./target/release/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

# 构建项目
cargo build --release

# 可执行文件位于
.\target\release\palpo.exe

数据库设置和迁移

1. 创建数据库和用户

macOS/Linux

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

# 创建数据库和用户
sudo -u postgres psql

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. 运行数据库迁移

# 进入 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. 使用预构建镜像 (推荐)

# 克隆项目获取配置文件
git clone https://github.com/palpo/palpo.git
cd palpo/deploy/docker

# 编辑配置文件
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

3. Docker Compose 配置示例

version: '3.8'

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: palpo
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: palpo
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U palpo"]
      interval: 10s
      timeout: 5s
      retries: 5

  palpo:
    image: palpo:latest
    ports:
      - "8008:8008"
      - "8448:8448"
    environment:
      DATABASE_URL: "postgres://palpo:changeme@postgres:5432/palpo"
      PALPO_CONFIG: '/var/palpo/palpo.toml'
    volumes:
      - ./palpo.toml:/var/palpo/palpo.toml
      - palpo_media:/var/palpo/media
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:
  palpo_media:

开发环境设置

1. 安装开发工具

# 安装 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/ 目录中查看。

故障排除

数据库相关问题

  1. 迁移失败:
# 检查数据库连接
psql $DATABASE_URL -c "SELECT version();"

# 检查迁移状态
diesel migration list

# 重置数据库 (谨慎使用)
dropdb palpo && createdb palpo
diesel migration run
  1. 权限问题:
-- 确保用户有足够权限
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;
  1. 连接问题:
# 测试数据库连接
pg_isready -h localhost -p 5432 -U palpo

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

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

常见问题

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

日志调试

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

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

更多调试信息请参考：

在本页上