服务端开发

Mosaic 的生产服务端使用 Go + chi + pgx + goose 构建。本文介绍本地开发环境搭建。

想找 Rust 版本？它位于 server/，作为参考实现保留，并非已部署的后端。

前置条件

Go 1.26+
PostgreSQL 15+，带 pgvector 扩展
FFmpeg（可选，用于视频处理）

环境搭建

1. 克隆并进入服务端目录

git clone https://github.com/crayonlu/Mosaic
cd Mosaic/server-go

2. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，填入你的数据库连接信息

3. 创建数据库

createdb mosaic
# 或
psql -c "CREATE DATABASE mosaic;"

启用 pgvector 扩展：

psql -d mosaic -c "CREATE EXTENSION IF NOT EXISTS vector;"

4. 启动服务端

go run ./cmd/mosaic-server

服务端会自动：

从 .env 读取配置
连接 PostgreSQL
通过 goose 应用待执行的数据库迁移
在配置的端口上启动监听（默认：8080）

项目结构

server-go/
├── cmd/
│   ├── mosaic-server/     # 入口点
│   └── baseline-sqlx/     # 一次性迁移记账
├── internal/
│   ├── config/      # 环境变量配置
│   ├── httpapi/     # 路由、处理器、中间件
│   ├── service/     # 业务逻辑
│   ├── store/       # PostgreSQL 数据访问
│   ├── domain/      # 类型与共享契约
│   ├── adapters/    # AI 与外部集成
│   ├── auth/        # JWT 与密码哈希
│   ├── media/       # 图片与视频处理
│   └── storage/     # 文件存储（本地/S3）
├── migrations/      # SQL 迁移文件
├── third-party/     # 附带许可证
├── Dockerfile
└── .env.example

主要依赖

包	用途
chi	HTTP 路由
pgx	PostgreSQL 驱动与连接池
goose	迁移执行器
golang-jwt	JWT 认证
golang.org/x/crypto	密码哈希
pgvector	向量嵌入，用于语义搜索

常用命令

go run ./cmd/mosaic-server   # 启动服务端
go build ./...               # 构建所有包
go test ./...                # 运行测试
go vet ./...                 # 静态检查

数据库迁移

迁移文件位于 server-go/migrations/（进入该目录后即 migrations/），服务端启动时通过 goose 自动执行。每个迁移是带时间戳的 SQL 文件，必须以 -- +goose Up 指令开头； -- +goose Down 段可选。已执行集合记录在 goose_db_version 表中。添加新迁移：

touch migrations/$(date -u +"%Y%m%d%H%M%S")_your_description.sql

在文件中编写 -- +goose Up 的 SQL，下次重启服务端时会自动应用。Go 目录镜像了 Rust 目录的迁移并加上 goose 指令；两者的 SQL 主体一致。

服务端开发

On this page