SnapLedger/docs/infrastructure-setup.md

SnapLedger 基础设施实施文档

目标服务器: Remote_MisakaServer 日期: 2026-05-21 对应 PRD: Phase 1 - 数据通道基建

1. 服务器现有环境

1.1 MinIO (systemd 服务)

项目	值
部署方式	systemd 原生服务
二进制路径	/usr/local/bin/minio
API 端口	9002
Console 端口	9001
数据目录	/mnt/disk1
管理账号	myminioadmin / myminioadmin
mc 客户端	已安装，本地 alias mylocal → localhost:9002

1.2 PostgreSQL (systemd 服务)

项目	值
部署方式	systemd 原生服务
版本	PostgreSQL 18.3 (Ubuntu 18.3-1.pgdg22.04+1)
二进制路径	/usr/lib/postgresql/18/bin/postgres
端口	5432
数据目录	/var/lib/postgresql/18/main
配置文件	/etc/postgresql/18/main/postgresql.conf
认证方式	本地 peer / 远程 scram-sha-256
管理账号	postgres (系统用户，通过 sudo -u postgres psql 访问)
现有数据库	CompanyDB, ai_image_vault, postgres
现有角色	admin, companydb_user, img_vault, mcp_user, postgres

---

2. 实施计划

Step 1: MinIO - 创建 Bucket

• 操作: 使用 mc 创建名为 snapledger 的存储桶
• 用途: 存储用户上传的支付截图
• 策略: 限制 Bucket 仅允许应用访问，不公开

Step 2: MinIO - 创建 Access Key

• 操作: 使用 mc admin user add 创建专用访问密钥
• 用途: 后端 FastAPI 服务使用此密钥上传/读取图片
• 权限: 仅对 snapledger 桶有读写权限

Step 3: PostgreSQL - 创建数据库与用户

• 操作: 创建 snapledger 数据库和专用用户 snapledger_user
• 权限: 该用户仅拥有 snapledger 数据库的完整权限

Step 4: PostgreSQL - 创建基础表

• 操作: 根据 PRD 数据模型创建 transactions 表
• 内容: 包含原始数据层、核心业务层、审计运维层全部字段

---

3. 详细操作命令

3.1 MinIO - 创建 Bucket

# 在服务器上执行
mc mb mylocal/snapledger

3.2 MinIO - 创建 Access Key 并授权

# 创建策略文件，限制仅访问 snapledger 桶
cat > /tmp/snapledger-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::snapledger",
        "arn:aws:s3:::snapledger/*"
      ]
    }
  ]
}
EOF

# 创建策略
mc admin policy create mylocal snapledger-policy /tmp/snapledger-policy.json

# 创建服务账号 (Access Key / Secret Key 由 mc 自动生成)
mc admin user svcacct add mylocal myminioadmin --description 'SnapLedger app service account'

# 将策略绑定到新生成的服务账号 (使用上一步输出的 Access Key)
mc admin policy attach mylocal snapledger-policy --user <生成的AccessKey>

3.3 PostgreSQL - 创建数据库与用户

# 在服务器上通过 postgres 系统用户执行
# 先生成随机密码
PG_PASS=$(openssl rand -base64 24)
sudo -u postgres psql

# SQL 语句
CREATE USER snapledger_user WITH PASSWORD '${PG_PASS}';
CREATE DATABASE snapledger OWNER snapledger_user;
GRANT ALL PRIVILEGES ON DATABASE snapledger TO snapledger_user;

3.4 PostgreSQL - 创建基础表

# 连接到 snapledger 数据库
sudo -u postgres psql -d snapledger

-- 授予 schema 权限
GRANT ALL ON SCHEMA public TO snapledger_user;

-- 创建 transactions 表
CREATE TABLE IF NOT EXISTS transactions (
    -- 原始数据层
    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    image_object_key    VARCHAR NOT NULL,
    original_filename   VARCHAR,
    user_note           TEXT,
    upload_time         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    process_status      VARCHAR(20) NOT NULL DEFAULT 'PENDING'
                            CHECK (process_status IN ('PENDING','PROCESSING','COMPLETED','FAILED')),

    -- 核心业务层 (AI 填充)
    transaction_type    VARCHAR(20) CHECK (transaction_type IN ('EXPENSE','INCOME','TRANSFER')),
    amount              DECIMAL(10,2),
    merchant_name       VARCHAR,
    source_app          VARCHAR,
    transaction_date    TIMESTAMPTZ,
    category            VARCHAR,
    order_number        VARCHAR,

    -- 审计运维层
    llm_raw_response    JSONB,

    -- 索引与约束
    created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 创建索引
CREATE INDEX idx_transactions_process_status ON transactions (process_status);
CREATE INDEX idx_transactions_upload_time   ON transactions (upload_time DESC);
CREATE INDEX idx_transactions_source_app    ON transactions (source_app);
CREATE INDEX idx_transactions_order_number  ON transactions (order_number) WHERE order_number IS NOT NULL;

-- 授权
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO snapledger_user;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO snapledger_user;

---

4. 预期产出

完成以上步骤后，将产出以下资源：

MinIO

资源	名称	说明
Bucket	snapledger	存储支付截图
Access Key	服务账号，Access Key / Secret Key 自动生成	后端服务专用
Policy	snapledger-policy	仅限 snapledger 桶读写

PostgreSQL

资源	名称	说明
Database	snapledger	应用主数据库
User	snapledger_user	应用专用账号
Table	transactions	交易记录核心表
Indexes	4 个	加速状态查询、时间排序、来源筛选、订单去重

连接信息

详见 docs/connections.yaml（已加入 .gitignore，不会提交到仓库）。

---

5. 验证步骤

1. MinIO Bucket: mc ls mylocal/snapledger 确认桶存在
2. MinIO Access Key: 使用新密钥配置 mc alias 并上传测试文件
3. PostgreSQL 连接: sudo -u postgres psql -d snapledger -c "\dt" 确认表已创建
4. 表结构验证: \d transactions 确认字段与索引完整