SSD Nodes Learn Hosting plans →
Panduan Matt ConnorOleh Matt Connor

Cara Self-host Langfuse untuk Ejen AI di VPS

Ketahui cara mengehos sendiri Langfuse di VPS anda. Panduan ini merangkumi konfigurasi tag imej, tetapan TLS, pengurusan storan ClickHouse, serta strategi sandaran data.

Mengapa perlu menjejak ejen AI

Anda mengehos sendiri Langfuse untuk melihat perkara yang sebenarnya dilakukan oleh ejen anda semasa satu larian. Langfuse ialah alat kebolehcerapan LLM (model bahasa besar) sumber terbuka. Ia merekodkan setiap prompt, setiap respons model, setiap panggilan alat dan setiap token, kemudian mengumpulkannya di bawah satu jejak yang boleh anda buka dan baca. Menjalankannya pada VPS anda sendiri bermakna prompt tersebut tidak pernah meninggalkan pelayan yang anda kawal.

Sebab untuk melakukannya adalah jelas. Anda tidak boleh membaiki masalah kos atau masalah kualiti yang tidak dapat anda lihat. Invois pembekal memberitahu anda bahawa hari Selasa menelan kos empat kali ganda berbanding hari Isnin. Satu jejak memberitahu anda larian ejen yang mana menyebabkannya, prompt yang mana berkembang sehingga 40,000 token, dan gelung cuba semula yang mana berjalan sebanyak sembilan kali sebelum berhenti. Invois memberikan anda nombor tersebut. Jejak memberikan anda kod yang menghasilkannya.

Tiga istilah digunakan sepanjang panduan ini. Jejak (trace) ialah satu larian hujung-ke-hujung ejen anda. Pemerhatian (observation) ialah satu langkah di dalam larian tersebut: span untuk kod biasa, generasi untuk panggilan kepada model. Skor (score) ialah nombor yang dilampirkan pada satu jejak, daripada semakan manusia atau penilai automatik. Langfuse menggunakan OpenTelemetry (OTel), piawaian neutral vendor untuk penjejakan teragih, jadi instrumentasi yang anda miliki sudah boleh dihalakan kepadanya.

Perkara yang sebenarnya dijalankan oleh Langfuse yang dihoskan sendiri

Langfuse v4 bukan sekadar satu kontena. Ia terdiri daripada dua kontena aplikasi dan empat servis storan, dan pada satu VPS, kesemua enam komponen ini berjalan pada pelayan anda.

  • langfuse-web menyediakan antara muka web dan API penyerapan (ingestion API).
  • langfuse-worker mengosongkan baris gilir di latar belakang. Ia menghurai kelompok penyerapan, mengira kos, dan menjalankan kerja pengekalan (retention job) pada waktu malam.
  • Postgres menyimpan data transaksi seperti pengguna, organisasi, projek, kunci API dan prompt.
  • ClickHouse menyimpan data jejak (trace data) itu sendiri, iaitu pemerhatian dan skor. Ia merupakan storan lajur yang dibina untuk pertanyaan analitik, itulah sebabnya papan pemuka yang memproses seratus juta baris data masih boleh memberikan respons dengan pantas.
  • Redis berfungsi sebagai baris gilir dan cache yang terletak di antara web dan pekerja (worker).
  • MinIO memberikan anda storan objek yang serasi dengan S3 pada pelayan tersebut. Ia menyimpan setiap peristiwa masuk mentah serta sebarang media yang anda lampirkan.

Langfuse menerbitkan keperluan sumber minimum bagi setiap komponen yang dijalankannya. Carta di bawah menunjukkan tiga komponen yang melakukan kerja tersebut.

CartaLangfuse published minimum resources per component
Data di sebalik carta ini
[
  {
    "label": "ClickHouse",
    "cpu_cores": 2,
    "memory_gib": 8
  },
  {
    "label": "Langfuse web",
    "cpu_cores": 2,
    "memory_gib": 4
  },
  {
    "label": "Langfuse worker",
    "cpu_cores": 2,
    "memory_gib": 4
  }
]

ClickHouse sahaja memerlukan 8 GiB memori. Kontena web dan pekerja masing-masing memerlukan 4 GiB. Itu adalah had minimum yang diterbitkan untuk 3 komponen dalam carta. Halaman yang sama menyenaraikan Postgres pada 4 GiB, Redis atau Valkey pada 1.5 GiB dan MinIO pada 4 GiB, jadi jumlah minimum untuk kesemua enam komponen adalah 25.5 GiB. Panduan Docker Compose projek itu sendiri mengesyorkan sekurang-kurangnya 4 teras, 16 GiB memori dan sekitar 100 GiB storan untuk satu mesin. Jumlah itu kurang daripada hasil tambah had minimum komponen, jadi anggap 16 GiB sebagai jumlah paling rendah yang diperlukan oleh pelayan Compose yang dikongsi, bukan sebagai ruang tambahan.

Jangan cuba ini pada pelan 2 GiB. ClickHouse akan bermula, menerima penulisan untuk seketika, kemudian terhenti semasa proses penggabungan latar belakang (background merge), kerana proses penggabungan memuatkan sebahagian besar jadual ke dalam memori. Anda akan melihat docker compose ps melaporkan kontena clickhouse sebagai restarting, dmesg mengandungi baris seperti Out of memory: Killed process 1234 (clickhouse-serv), dan setiap papan pemuka Langfuse akan memaparkan ralat 500. Di bawah tekanan yang lebih ringan, ClickHouse akan menolak pertanyaan tersebut dan merekodkan DB::Exception: Memory limit (total) exceeded dalam log. Enam belas adalah angka yang perlu dirancang. Jika VPS yang sama bertujuan untuk menjalankan aplikasi lain, peruntukkan bajet secara berasingan untuk aplikasi tersebut, kerana tindanan (stack) yang agak ringan seperti ruang kerja AFFiNE yang dihoskan sendiri juga memerlukan gigabait memorinya sendiri dan ClickHouse tidak akan melepaskan sebarang memori yang telah digunakannya.

Menggunakan Langfuse dengan Docker Compose

Klon repositori tersebut. Stak, pendawaian, dan persekitaran lalai semuanya terkandung dalam docker-compose.yml miliknya.

git clone https://github.com/langfuse/langfuse.git
cd langfuse

Setiap nilai yang perlu anda ubah ditandakan sebagai # CHANGEME dalam fail tersebut. Jana tiga rahsia aplikasi terlebih dahulu.

openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -base64 32   # SALT
openssl rand -hex 32      # ENCRYPTION_KEY

ENCRYPTION_KEY mestilah 256 bit yang ditulis sebagai 64 aksara heksadesimal, iaitu tepat seperti yang dicetak oleh openssl rand -hex 32. Ia menyulitkan nilai sensitif semasa dalam simpanan, termasuk sebarang kunci pembekal LLM yang anda simpan dalam instans tersebut. Mengubahnya selepas data wujud akan menyebabkan baris tersebut tidak lagi boleh dinyahsulit, jadi anggap ia sebagai kekal sejak but pertama. SALT digunakan untuk melakukan hash pada kunci API Langfuse anda, jadi mengubahnya akan membatalkan setiap kunci yang sedang digunakan oleh ejen anda.

Kemudian, tetapkan POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH, dan MINIO_ROOT_PASSWORD. Kata laluan MinIO muncul di empat tempat: sekali sebagai MINIO_ROOT_PASSWORD, kemudian sekali lagi sebagai LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY, dan LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. Jika terlepas satu, MinIO akan menolak klien tersebut dengan SignatureDoesNotMatch, yang akan muncul dalam log pekerja sementara antara muka web masih kelihatan sihat. Menyimpan nilai-nilai ini dalam fail env dan bukannya dalam fail compose yang dijejaki adalah corak yang dibincangkan dalam fail env dan rahsia Docker Compose.

Tetapkan tag imej sebelum anda bermula

Fail yang dibekalkan menggunakan docker.langfuse.com/langfuse/langfuse:4 dan docker.langfuse.com/langfuse/langfuse-worker:4. Tag tersebut sentiasa berubah. Langfuse menjalankan migrasi Postgres dan ClickHouse secara automatik semasa permulaan, jadi docker compose pull rutin beberapa bulan kemudian akan menjadi migrasi skema yang tidak dirancang pada pangkalan data yang tidak anda sandarkan pada pagi itu. Tetapkan kedua-duanya kepada satu keluaran dalam docker-compose.override.yml, yang akan digabungkan oleh Compose di atas fail yang dibekalkan supaya git pull kemudian tidak akan bercanggah dengan suntingan anda. Imej yang sama diterbitkan di Docker Hub, iaitu tempat override di bawah menariknya.

services:
  langfuse-web:
    image: docker.io/langfuse/langfuse:4.72.0
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:4.72.0

Versi 4.3.1 merupakan keluaran 4.3 semasa pada Ogos 2026. Keluaran telah dikeluarkan dengan pantas sejak itu, dan v4.56.0 adalah yang terkini di GitHub setakat 11 Oktober 2026. Override di atas menggunakan v4.72.0, yang terkini di GitHub setakat 31 Oktober 2026. Semak halaman keluaran GitHub projek tersebut, tetapkan apa sahaja yang terkini pada hari anda melakukan deployment, kemudian pindahkan nombor tersebut secara sengaja. Sesetengah imej storan dalam fail yang dibekalkan memerlukan layanan yang sama, kerana tagnya juga berubah. postgres:17 (lalai bagi pemboleh ubah POSTGRES_VERSION) dan redis:7 mengikut versi utama. Fail yang dibekalkan kini menggunakan tag versi tepat untuk docker.io/clickhouse/clickhouse-server, menetapkan versi ClickHouse yang tepat. Peraturan itu tidak khusus untuk Langfuse: penjejak senaman openGym yang dihoskan sendiri menjalankan sebahagian kecil daripada stak ini dan masih memerlukan tag git yang dinamakan, kerana apa sahaja yang memigrasikan pangkalan datanya sendiri semasa permulaan boleh mengubah penarikan rutin menjadi perubahan skema.

Jalankan ia.

docker compose up -d
docker compose ps
docker compose logs -f langfuse-worker

But pertama menjalankan migrasi, jadi berikan masa dua atau tiga minit sebelum ada respons. Kontena web mencatatkan Ready sebaik sahaja ia sedia. docker compose ps sepatutnya menyenaraikan enam servis dalam status running. Jika kontena dimulakan semula dalam gelung, lognya mengandungi puncanya. Migrasi ClickHouse digunakan apabila kontena web bermula, jadi CLICKHOUSE_MIGRATION_URL yang salah akan muncul dalam docker compose logs langfuse-web, bukan dalam log pekerja yang anda pantau. Pemboleh ubah itu menggunakan protokol asli ClickHouse pada port 9000, bukan port HTTP 8123, dan menghalakannya ke 8123 akan merosakkan migrasi permulaan kontena web. Pekerja menjalankan migrasi latar belakang yang lebih perlahan, jadi lognya adalah tempat migrasi tersebut dilaporkan.

Semak kesihatan daripada pelayan itu sendiri.

curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/ready

Panggilan /api/public/health biasa hanya membuktikan proses API masih hidup, kerana secara lalai ia tidak menyemak pangkalan data. Borang failIfDatabaseUnavailable=true adalah yang perlu dipantau oleh alat pemantau, dan ia mengembalikan 503 apabila pangkalan data tidak dapat dicapai. /api/public/ready mengembalikan 200 apabila kontena web sedia menerima trafik, dan 500 sebaik sahaja ia diarahkan untuk ditutup. Kedua-duanya adalah semakan HTTP biasa, jadi halaman status Uptime Kuma boleh memantaunya dan memberitahu anda bahawa stak tersebut tidak berfungsi sebelum ejen anda mengetahuinya.

Letakkan TLS di hadapan dan tutup port tambahan

Fail compose yang dibekalkan menerbitkan 3000:3000 untuk kontena web dan 9090:9000 untuk MinIO. Kedua-duanya terikat pada setiap antara muka. Pada IP awam, ini bermakna sesiapa sahaja yang mengimbas port 3000 akan sampai ke halaman pendaftaran anda, dan sesiapa yang mengimbas 9090 akan berhubung dengan bucket yang menyimpan prompt mentah anda.

Peraturan firewall sahaja tidak menutup port tersebut. Docker menulis peraturan DNAT sendiri ke dalam jadual nat, dan peraturan tersebut dinilai sebelum peraturan penapis ufw melihat paket itu, jadi ufw deny 3000 membiarkan port yang diterbitkan itu terbuka. Masalah ini cukup kerap berlaku sehingga mempunyai panduan tersendiri: mengapa port yang diterbitkan Docker memintas ufw. Sebaliknya, ikat pada loopback dalam fail override anda. Gunakan !override dengan Docker Compose 2.24.4 atau lebih baharu untuk menggantikan port yang diterbitkan; senarai biasa akan bercantum dengan ikatan asal.

services:
  langfuse-web:
    ports: !override
      - "127.0.0.1:3000:3000"
    environment:
      NEXTAUTH_URL: https://langfuse.example.com
  minio:
    ports: !override
      - "127.0.0.1:9090:9000"
      - "127.0.0.1:9091:9001"

NEXTAUTH_URL mestilah alamat awam yang tepat termasuk skema, kerana aliran log masuk membina URL panggil balik (callback URL) daripada nilai tersebut. Jika dibiarkan sebagai http://localhost:3000 di belakang proksi HTTPS, pusingan log masuk akan menghantar pelayar ke lokasi yang tidak dapat dicapai.

Sekarang, halakan reverse proxy ke 127.0.0.1:3000 dan biarkan ia memegang sijil tersebut. Untuk Traefik dalam projek Compose yang sama, halakan ke langfuse-web:3000 melalui rangkaian Compose menggunakan label yang dibincangkan dalam menjalankan beberapa aplikasi di belakang satu reverse proxy Traefik. Caddy melakukan tugas yang sama dalam dua baris jika Langfuse adalah satu-satunya aplikasi pada pelayan tersebut. Sahkan dengan curl -sI https://langfuse.example.com/api/public/ready, kemudian pastikan dari mesin kedua bahawa curl http://YOUR_IP:3000 tidak dapat disambungkan.

Satu peringatan mengenai MinIO. Langfuse memberikan URL pra-tandatangan (presigned URLs) yang menghala ke endpoint S3 tersebut, kepada SDK yang memuat naik media dan kepada pelayar anda yang memuatkannya. Jadi, jika anda menggunakan trace berbilang mod yang membawa imej atau audio, MinIO yang hanya terikat pada loopback bermakna lampiran tersebut tidak akan dimuat naik dari mesin lain atau dimuatkan dalam pelayar anda. Baca halaman konfigurasi storan blob sebelum melakukan proksi, kerana endpoint yang ditulis ke dalam URL pra-tandatangan, LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, mestilah sepadan dengan apa yang anda terbitkan. Trace teks biasa tidak terjejas.

Cipta akaun anda pada lawatan pertama, kemudian pastikan instans tersebut kekal milik anda. Tetapkan AUTH_DISABLE_SIGNUP=true sebaik sahaja akaun anda wujud, supaya orang asing yang sampai ke halaman tersebut tidak boleh mendaftar sama sekali. Langfuse juga mempunyai LANGFUSE_ALLOWED_ORGANIZATION_CREATORS, yang mengehadkan siapa yang boleh mencipta organisasi, tetapi ia adalah ciri Enterprise Edition dan hanya berkuat kuasa dengan kunci lesen. Jika anda sudah menjalankan Authentik sebagai penyedia identiti anda sendiri, Langfuse menerima sambungan OIDC standard, jadi akaun akan diuruskan bersama aplikasi anda yang lain dan bukannya tersimpan dalam senarai kata laluan yang hanya diketahui oleh pelayan ini.

Hantar surih pertama anda

Cipta projek dalam antara muka web dan salin kunci awam serta kunci rahsia daripada tetapan projek. Python SDK membaca tiga pemboleh ubah persekitaran.

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"

LANGFUSE_BASE_URL ialah nama pemboleh ubah dalam SDK v4, yang dikeluarkan pada Mac 2026. Kod lama dan panduan lama menggunakan LANGFUSE_HOST. Jika surih anda mendarat di Langfuse Cloud dan bukannya pelayan anda, punca masalahnya ialah base URL yang tidak ditetapkan, kerana lalai sistem menghala ke instans yang dihoskan.

Python SDK v5 semasa memerlukan Python 3.11 atau lebih baharu dan Langfuse v4.59.0 atau lebih baharu yang dihoskan sendiri, yang dipenuhi oleh pelayan yang dipinkan di atas.

pip install langfuse opentelemetry-instrumentation-anthropic anthropic
import os
from anthropic import Anthropic
from langfuse import get_client, observe
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor

AnthropicInstrumentor().instrument()
langfuse = get_client()
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

@observe(as_type="tool")
def lookup_order(order_id: str) -> str:
    return f"order {order_id}: shipped"

@observe()
def handle_request(question: str) -> str:
    context = lookup_order("A-1042")
    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=512,
        messages=[{"role": "user", "content": f"{context}\n\n{question}"}],
    )
    return message.content[0].text

if __name__ == "__main__":
    assert langfuse.auth_check()
    print(handle_request("Where is my order?"))
    langfuse.flush()

Dekorator @observe membuka pemerhatian di sekeliling fungsi, menangkap argumen dan nilai pulangannya, serta menyarangnya di bawah mana-mana pemerhatian yang sedang aktif. AnthropicInstrumentor ialah instrumentasi OpenTelemetry untuk klien Anthropic, dan ia menukarkan setiap panggilan messages.create menjadi penjanaan yang membawa nama model, penggunaan token dan kependaman, tanpa sebarang perubahan pada tapak panggilan.

Dua panggilan melakukan pemeriksaan untuk anda. langfuse.auth_check() mengembalikan False jika kunci tidak sah atau base URL salah, yang lebih pantas daripada tertanya-tanya mengapa papan pemuka kosong. langfuse.flush() menyekat sehingga span yang beratur dihantar, dan proses yang berjalan singkat memerlukannya, kerana SDK melakukan pemprosesan kelompok di latar belakang dan skrip yang tamat serta-merta akan membawa kelompok yang belum dihantar bersamanya. Jika seluruh pasukan menghantar surih dan bukannya satu skrip, tetapkan ketiga-tiga pemboleh ubah tersebut sekali sahaja dalam gerbang yang dilalui oleh ejen semua orang, bukannya dalam shell setiap individu. Inilah cara harness OneCLI yang dihoskan sendiri memastikan setiap larian rakan sekerja diinstrumentasikan sementara kunci kekal di satu tempat.

Mengapa penggunaan storan ClickHouse terus meningkat?

Data trace merupakan data yang paling cepat berkembang bagi kebanyakan pengguna yang menguruskan pelayan sendiri. Setiap pelaksanaan ejen akan menulis satu baris bagi setiap langkah, dan input serta output disimpan sepenuhnya. Oleh itu, ejen yang aktif dengan prompt yang panjang akan menghasilkan jumlah bait yang jauh lebih besar setiap hari berbanding aplikasi yang dipantaunya. Jika dibiarkan, ClickHouse akan memenuhi cakera, dan cakera yang penuh akan menghentikan proses ingestion dan bukannya sekadar melambatkannya.

Terdapat dua perkara berasingan yang menyebabkan pertumbuhan ini, dan kedua-duanya memerlukan penyelesaian yang berbeza.

Pertama ialah data trace anda sendiri, dan penyelesaiannya adalah tetapan pengekalan (retention). Pada instans yang diurus sendiri, pengekalan data merupakan ciri Enterprise Edition dan memerlukan lesen. Tanpa lesen, Langfuse akan menyimpan trace, pemerhatian, skor dan media selama-lamanya. Oleh itu, pastikan saiz cakera mencukupi dan gunakan amaran cakera di akhir bahagian ini. Dengan lesen, pemilik projek dan pentadbir boleh membuka tetapan projek dan menetapkan tempoh pengekalan data dalam hari. Langfuse menerima tempoh minimum 3 hari. Satu tugasan harian kemudiannya akan memilih trace, pemerhatian, skor dan aset media yang lebih lama daripada tempoh tersebut lalu memadamkannya daripada ClickHouse dan storan blob, kecuali media yang dikaitkan dengan item dataset yang disimpan. Tugasan ini memerlukan kebenaran DeleteObject pada bucket, yang sudah pun dimiliki oleh kelayakan root MinIO dalam fail compose lalai. Pemadaman adalah kekal, jadi konfigurasikan eksport storan blob terlebih dahulu jika anda memerlukan sejarah jangka panjang. Jangan tulis klausa TTL secara manual pada jadual milik Langfuse: tugasan pengekalan adalah mekanisme yang memastikan ClickHouse dan bucket selari, manakala TTL manual hanya akan memadamkan data pada satu bahagian sahaja.

Pilih tempoh masa berdasarkan penggunaan sebenar anda. Semakan kos dan kualiti biasanya dilakukan pada data yang berusia beberapa hari, bukan berbulan-bulan. Tiga puluh hari adalah permulaan yang munasabah untuk pasukan kecil, dan 14 hari sudah memadai jika anda hanya membuka trace apabila berlaku kerosakan.

Kedua ialah jadual log sistem ClickHouse sendiri. Perkara ini sering mengejutkan pengguna kerana cakera terus penuh walaupun pengekalan telah dikonfigurasikan. ClickHouse menulis trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log dan latency_log untuk diagnostik dalamannya sendiri, ia dihantar tanpa TTL, dan Langfuse tidak pernah membacanya. Cari punca sebenar penggunaan ruang cakera terlebih dahulu.

SELECT table, formatReadableSize(size) AS size, rows FROM (
    SELECT table, database, sum(bytes) AS size, sum(rows) AS rows
    FROM system.parts
    WHERE active
    GROUP BY table, database
    ORDER BY size DESC
)

Jalankan arahan tersebut dengan docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". Jika jadual sistem berada di kedudukan teratas, matikan ia menggunakan overlay konfigurasi, kerana ClickHouse akan menggabungkan setiap fail dalam /etc/clickhouse-server/config.d/ ke atas konfigurasi utamanya semasa dimulakan.

<clickhouse>
    <trace_log remove="1"/>
    <text_log remove="1"/>
    <opentelemetry_span_log remove="1"/>
    <asynchronous_metric_log remove="1"/>
    <metric_log remove="1"/>
    <latency_log remove="1"/>
</clickhouse>

Lekapkan (mount) fail tersebut dan mulakan semula ClickHouse.

services:
  clickhouse:
    volumes:
      - ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:ro

Tindakan ini akan menghentikan penulisan baharu. Baris yang sudah ada pada cakera akan kekal di situ, jadi tuntut semula ruang tersebut secara eksplisit dengan DROP TABLE IF EXISTS system.trace_log dan lakukan perkara yang sama untuk setiap jadual yang anda alih keluar. Jika anda lebih suka mengekalkan diagnostik tersebut, alternatifnya adalah dengan menetapkan TTL yang agresif pada setiap jadual sebagai ganti kepada remove="1", seperti yang diterangkan dalam dokumentasi penskalaan Langfuse. Arahan TTL tersebut hanya terpakai apabila jadual sistem mula dicipta, jadi bagi pemasangan sedia ada, dokumentasi yang sama juga akan membimbing anda untuk melakukan pengubahsuaian pada jadual tersebut.

Satu lagi jadual yang perlu diketahui ialah blob_storage_file_log yang menjejaki fail peristiwa yang dimuat naik ke bucket anda. Jika anda juga menetapkan polisi kitaran hayat (lifecycle policy) pada bucket, berikan jadual tersebut TTL yang sepadan supaya kedua-duanya tidak terasing.

ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;

Tetapkan juga amaran df -h yang mudah pada cakera data. Data trace tidak berkembang secara sekata. Ia berkembang pada hari anda melancarkan ejen baharu, dan tanda pertama perkara ini berlaku tidak sepatutnya adalah kegagalan proses ingestion.

Sandarkan Postgres dan ClickHouse

Sandaran Langfuse terdiri daripada tiga bahagian. Postgres menyimpan pengguna, organisasi, projek dan API key anda. ClickHouse menyimpan trace. MinIO menyimpan data peristiwa mentah. Jika anda memulihkan Postgres sahaja, anda akan mendapat log masuk yang berfungsi tetapi tiada sejarah. Jika anda memulihkan ClickHouse sahaja, anda akan mendapat sejarah tetapi tiada sesiapa boleh log masuk untuk melihatnya. Pemisahan ini bukan unik bagi Langfuse, dan meja bantuan Chatwoot yang dihoskan sendiri mempunyai struktur yang sama, di mana dump Postgres yang diambil tanpa direktori muat naik akan memulihkan perbualan yang semua lampirannya telah hilang.

Postgres ialah pg_dump biasa, iaitu kaedah yang digunakan oleh dokumentasi sandaran Langfuse untuk pemasangan Docker.

docker compose exec -T postgres pg_dump -U postgres postgres \
  | gzip > langfuse-pg-$(date +%F).sql.gz

ClickHouse memerlukan lebih perhatian, kerana direktori data langsung yang disalin semasa proses merge sedang berjalan bukanlah sandaran yang konsisten. Pendekatan mudah pada satu pelayan adalah dengan menghentikan container dan mengarkibkan volume tersebut.

docker compose stop clickhouse
docker volume ls | grep clickhouse
docker run --rm -v langfuse_langfuse_clickhouse_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/langfuse-ch-$(date +%F).tar.gz -C /data .
docker compose start clickhouse

Gunakan nama volume yang dipaparkan oleh docker volume ls, bukan nama yang tertulis dalam YAML. Fail tersebut mengisytiharkan langfuse_clickhouse_data, dan Compose meletakkan awalan nama projek padanya, jadi klon dalam direktori bernama langfuse akan menghasilkan langfuse_langfuse_clickhouse_data. Jika anda tersilap, docker run akan mencipta volume kosong yang baharu tanpa sebarang amaran, dan arkib anda tidak akan mengandungi apa-apa.

Langfuse memuat naik data peristiwa mentah ke bucket pada setiap permintaan ingestion dan membacanya semula untuk mencuba semula kerja ingestion yang gagal, jadi penghentian ClickHouse yang singkat biasanya bermakna worker akan mencuba semula selepas itu. Lakukan ini pada waktu trafik rendah dan pastikan ia singkat. Untuk instance yang lebih sibuk, pernyataan BACKUP DATABASE default TO S3(...) milik ClickHouse sendiri akan menulis sandaran yang konsisten tanpa perlu menghentikan pelayan. MinIO adalah bahagian ketiga, dan mc mirror atau replikasi MinIO ke bucket di luar pelayan akan melindunginya. Apa sahaja yang anda hasilkan, pindahkan ia keluar dari pelayan, itulah tujuan sandaran restic yang disulitkan pada VPS.

Redis menyimpan baris gilir dan cache. Kehilangannya akan menyebabkan kerja dalam baris gilir terbuang, walaupun fail peristiwa mentahnya masih kekal dalam bucket.

Amaran tentang konsistensi adalah nyata dan perlu dinyatakan dengan jelas. Postgres dan ClickHouse di-dump pada waktu yang berbeza, jadi pemulihan boleh menyebabkan baris projek tiada trace, atau trace milik projek yang sudah tidak wujud. Langfuse boleh bertoleransi dengan perkara itu, tetapi ambil kedua-dua dump tersebut secara berdekatan dan dalam waktu trafik rendah. Bucket peristiwa adalah jaring keselamatan yang sebenar, kerana Langfuse memuat naik data peristiwa mentah ke sana pada setiap permintaan ingestion.

Lakukan pemulihan ke dalam stack percubaan sekurang-kurangnya sekali. Itulah cara anda mengetahui tentang nama volume yang salah sekarang, bukannya semasa gangguan perkhidmatan berlaku.

Perkara yang perlu dilihat terlebih dahulu

Empat perkara ini wajar diberi perhatian pada minggu pertama.

  • Kos setiap trace. Langfuse mengira kos berdasarkan nama model dan penggunaan token, jadi susun trace mengikut kos dan baca trace yang paling mahal dari awal hingga akhir. Jawapannya biasanya berpunca daripada prompt yang semakin panjang: keseluruhan dokumen yang ditampal ke dalam konteks, atau sejarah perbualan yang tidak dipotong. Sebaik sahaja anda dapat melihatnya, mengawal kos ejen AI anda menjadi satu tugasan kejuruteraan dan bukannya sekadar tekaan.
  • Pecahan penggunaan token mengikut input dan output. Token input adalah banyak dan murah, token output adalah sedikit dan mahal, manakala input yang dicache adalah lebih murah lagi. Perakaunan yang sama dihuraikan dalam cara penggunaan token Claude Code dikira, dan ia terpakai untuk mana-mana ejen yang anda tulis sendiri.
  • Persentil kependaman (latency). Nilai median menyembunyikan masalah sebenar. p95 dan p99 adalah tempat berlakunya timeout, dan di dalam gelung ejen, panggilan alat yang perlahan pada p95 akan didarabkan dengan bilangan lelaran.
  • Panggilan alat yang gagal. Tapis pemerhatian mengikut tahap ERROR. Alat yang gagal sebanyak 5% daripada masa tidak kelihatan dalam kadar kejayaan agregat, tetapi sangat jelas dalam trace, di mana anda dapat melihat model mencuba semula dan kemudian membazirkan token untuk mencari jalan penyelesaian.

Tetapkan tempoh pengekalan data dan pilih papan pemuka yang akan anda semak setiap minggu pada hari yang sama anda melakukan deployment. Alat kebolehcerapan (observability) yang tidak dibuka oleh sesiapa hanyalah pangkalan data yang memenuhi ruang cakera.

FAQ

Berapakah memori yang diperlukan oleh Langfuse yang dihoskan sendiri?

Rancang untuk 4 teras CPU dan 16 GiB memori, iaitu saranan panduan Docker Compose Langfuse untuk satu mesin maya, ditambah kira-kira 100 GiB storan. Minimum komponen yang diterbitkan ialah 8 GiB untuk ClickHouse dan 4 GiB setiap satu untuk kontena web dan worker. Halaman yang sama menyenaraikan 4 GiB untuk Postgres, 1.5 GiB untuk Redis dan 4 GiB untuk MinIO, jadi kesemua enam komponen berjumlah 25.5 GiB, lebih daripada saranan 16 GiB Compose.

Mengapakah cakera ClickHouse saya terus penuh selepas saya menetapkan pengekalan data?

Tetapan pengekalan hanya meliputi data Langfuse sendiri. ClickHouse secara berasingan menulis jadual diagnostiknya trace_log, text_log, opentelemetry_span_log, metric_log, asynchronous_metric_log dan latency_log, dan jadual tersebut dihantar tanpa TTL. Jalankan pertanyaan system.parts yang dikumpulkan mengikut jadual untuk melihat jadual mana yang paling besar, kemudian nyahdayakan jadual yang tidak digunakan dengan entri remove="1" dalam fail di bawah /etc/clickhouse-server/config.d/, mulakan semula ClickHouse, dan buang jadual sedia ada untuk menuntut semula ruang yang telah digunakan.

Apakah tempoh pengekalan data minimum dalam Langfuse?

Tiga hari. Pengekalan ditetapkan bagi setiap projek dalam tetapan projek, atau melalui API Pengurusan Organisasi, dan tugasan malam akan memadamkan trace, pemerhatian, skor dan aset media yang lebih lama daripada tempoh tersebut daripada kedua-dua ClickHouse dan storan blob, kecuali media yang dikaitkan dengan item dataset yang disimpan. Pada instans yang dihoskan sendiri, ini merupakan ciri Enterprise Edition yang memerlukan kunci lesen. Tanpa kunci tersebut, data disimpan selama-lamanya. Pemadaman tidak boleh dibatalkan, jadi konfigurasikan eksport storan blob terlebih dahulu jika anda memerlukan sejarah melebihi tempoh tersebut.

Adakah saya perlu membuat sandaran untuk kedua-dua Postgres dan ClickHouse?

Ya, kerana kedua-duanya menyimpan maklumat yang berbeza. Postgres menyimpan pengguna, organisasi, projek dan kunci API, manakala ClickHouse menyimpan data trace itu sendiri. Pemulihan Postgres sahaja akan memberikan anda instans yang boleh dilog masuk tetapi kosong. Buat sandaran baldi MinIO juga, kerana ia menyimpan peristiwa mentah yang dikekalkan oleh Langfuse semasa ketibaan, yang merupakan perkara paling hampir dengan sumber kebenaran dalam tindanan tersebut.

Bolehkah saya menghalakan persediaan OpenTelemetry sedia ada ke Langfuse yang dihoskan sendiri?

Ya. Langfuse v4 dan SDK semasanya dibina berasaskan OpenTelemetry, dan instrumentasi OTel Anthropic serta OpenAI mengeksport terus kepadanya. Dalam Python, jalankan pip install langfuse opentelemetry-instrumentation-anthropic, panggil AnthropicInstrumentor().instrument() sekali semasa permulaan, dan tetapkan LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY serta LANGFUSE_BASE_URL kepada hos anda sendiri. Sahkan dengan langfuse.auth_check() sebelum mencari papan pemuka yang hilang.

Adakah artikel ini berguna?