Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
fix(docker): upgrade ParadeDB for CPUs without AVX2
wizardchenfa56b5b9322f
diff --git a/docker-compose.dev.yml b/docker-compose.dev.ymlindex d6e264dd8..9c8ac0fb5 100644--- a/docker-compose.dev.yml+++ b/docker-compose.dev.yml@@ -2,7 +2,7 @@services:# 只启动依赖的基础设施服务postgres:- image: paradedb/paradedb:v0.22.2-pg17+ image: paradedb/paradedb:v0.22.6-pg17container_name: WeKnora-postgres-devports:- "${DB_PORT:-5432}:5432"@@ -381,7 +381,7 @@ services:# ---------------------------------------------------------------------------# 复用 dev 已有的 ParadeDB 镜像,不额外拉 postgres 镜像langfuse-db-init:- image: paradedb/paradedb:v0.22.2-pg17+ image: paradedb/paradedb:v0.22.6-pg17container_name: WeKnora-langfuse-db-init-devdepends_on:postgres:diff --git a/docker-compose.yml b/docker-compose.ymlindex 09691cd76..35fd3cbdd 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -520,7 +520,7 @@ services:# 修改的PostgreSQL配置postgres:- image: paradedb/paradedb:v0.22.2-pg17+ image: paradedb/paradedb:v0.22.6-pg17container_name: WeKnora-postgresenvironment:- POSTGRES_USER=${DB_USER}@@ -798,7 +798,7 @@ services:# 一次性初始化脚本:在已有的 WeKnora-postgres 里创建 langfuse 数据库(幂等,数据库已存在则跳过)# 复用 WeKnora-postgres 的 ParadeDB 镜像,避免多拉一个 postgres 镜像langfuse-db-init:- image: paradedb/paradedb:v0.22.2-pg17+ image: paradedb/paradedb:v0.22.6-pg17container_name: WeKnora-langfuse-db-initdepends_on:postgres:diff --git a/docs/paradedb-upgrade.md b/docs/paradedb-upgrade.mdnew file mode 100644index 000000000..0a4cac257--- /dev/null+++ b/docs/paradedb-upgrade.md@@ -0,0 +1,119 @@+# ParadeDB 0.22.2 → 0.22.6 (PostgreSQL 17)++The production and development Compose files use `paradedb/paradedb:v0.22.6-pg17`.+The `langfuse-db-init` client uses the same image; Langfuse shares the Postgres+server and has its own database.++ParadeDB 0.22.2 compiles its Linux x86 extension for `x86-64-v3`, which can crash+with `Illegal instruction` on CPUs without AVX2. Version 0.22.6 lowers that+baseline to `x86-64-v2` (including SSE4.2 and POPCNT). This does **not** remove the+ARM `neoverse-n1` requirement or establish CPU compatibility for other services.++- [Upstream CPU fix](https://github.com/paradedb/paradedb/pull/4672)+- [0.22.6 release](https://github.com/paradedb/paradedb/releases/tag/v0.22.6)+- [Version-specific upgrade instructions](https://github.com/paradedb/paradedb/blob/v0.22.6/docs/deploy/upgrading.mdx)++## Existing deployments++Keep PostgreSQL on major version **17** and retain the existing data volume.+Do not use `docker compose down -v`, remove the volume, or substitute a PG18+image. This procedure covers the 0.22.2 → 0.22.6 patch upgrade; the Helm chart's+older 0.18.9 default is outside this validated upgrade path.++1. Stop application writers (`docker compose stop app` and, if enabled,+ `docker compose stop langfuse-web langfuse-worker`; stop a locally running+ development backend as well).+2. Take a restorable backup of all databases, including Langfuse and roles:++ ```bash+ umask 077+ docker compose exec -T postgres sh -c 'pg_dumpall -U "$POSTGRES_USER"' > paradedb-before-upgrade.sql+ ```++ Check the command succeeded and keep the backup outside the database volume.+ If the old server cannot start on this CPU, first preserve a cold snapshot of+ the stopped volume; make a logical backup on a compatible host or validate+ recovery from that snapshot before changing the only copy.+3. With the updated Compose file, replace only the database container:++ ```bash+ docker compose pull postgres+ docker compose up -d --no-deps --wait postgres+ ```++4. Complete the extension's SQL upgrade. Replacing the image alone leaves the+ existing database's `pg_extension` catalog at 0.22.2:++ ```bash+ docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -v ON_ERROR_STOP=1' <<'SQL'+ ALTER EXTENSION pg_search UPDATE TO '0.22.6';+ SELECT extname, extversion FROM pg_extension WHERE extname IN ('pg_search', 'vector');+ SELECT * FROM paradedb.version_info();+ SQL+ ```++ Run the same SQL in **every other database containing `pg_search`**, including+ `postgres` and any template or Langfuse database where it was installed.+ Do not install it into databases that do not use it. The catalog and+ `paradedb.version_info()` should both report 0.22.6; pgvector stays at 0.8.1.++ Migration `000099` also performs this step in the WeKnora database when the+ installed extension is 0.22.2–0.22.5 and the 0.22.6 package is available.+ It respects `app.skip_embedding` and leaves absent extensions and other+ release lines alone. If the migration+ ran before the new database image was installed, perform the SQL step above+ manually: applied migrations are not repeated. Older application releases+ without migration `000099` also require the manual step.+5. Resume the application writers, check migration status and run representative+ keyword/vector searches. No `REINDEX` or document re-ingestion is required+ by this patch upgrade. Preserve the backup until deployment checks pass.++For development use `docker compose -f docker-compose.dev.yml` in the commands+above. If rollback is necessary, restore the pre-upgrade backup/snapshot into a+separate volume with the old image. Merely changing the image tag back does not+reverse extension SQL changes; the migration's down file intentionally does not+attempt that.++## Reproducible verification++```bash+docker pull paradedb/paradedb:v0.22.2-pg17+docker pull paradedb/paradedb:v0.22.6-pg17+python3 scripts/test_paradedb_upgrade.py+```++The Python 3/Docker test uses uniquely named disposable containers and volumes,+publishes no ports, and does not access an existing WeKnora database. It saves+snapshots, query plans, a synthetic-data backup and logs in its printed output+directory, then removes only its own Docker resources.++It applies the real baseline migrations, seeds 720 embeddings across 798, 1024+and 3584 dimensions plus tenant/model/knowledge/session/message records, and+restarts the **same data volume** under the new image. It checks:++- All project table contents, columns, sequence values and index file identities.+- 104 keyword/vector queries: Chinese and English, missing/empty terms, KB,+ document and tag filters, disabled/NULL-enabled rows, Top-K and thresholds.+- Both normal planner choices and explicitly exercised HNSW index scans; BM25+ uses the production `|||` operator and `paradedb.score`. Equal BM25 scores use+ an ID tie-breaker to make comparisons reproducible.+- Extension migration, idempotence, skip-embedding, unavailable target and absent extension.+- Results after another restart; committed insert/update/delete and vector lookup.+- A fresh database with the full migration chain and a Chinese BM25 query.++This verifies the fixture and upgrade path, not every production corpus or+workload. Production backup/restore and representative retrieval checks remain+part of the deployment procedure.++### Validation recorded on 2026-09-17++The test passed on Linux ARM64 with PostgreSQL 17.9 and pgvector 0.8.1 in both+images: all 70 project table snapshots and all 104 retrieval results were+identical after upgrade and after restart, including scores and index file IDs.+A separate restore of the pre-upgrade dump into 0.22.2 also preserved all table+hashes/counts and sequence values.++The Linux AMD64 0.22.6 image was additionally started under QEMU user emulation+with `QEMU_CPU=Nehalem`. A CPUID probe confirmed AVX2 was absent; initialization,+BM25/HNSW index creation, keyword search and vector lookup passed. This is an+emulation check, not a test on the affected physical server or Kunpeng hardware.diff --git a/migrations/versioned/000099_pg_search_0226.down.sql b/migrations/versioned/000099_pg_search_0226.down.sqlnew file mode 100644index 000000000..689c5068d--- /dev/null+++ b/migrations/versioned/000099_pg_search_0226.down.sql@@ -0,0 +1,2 @@+-- No-op: pg_search SQL upgrades cannot be reversed by a schema rollback.+-- Restore a pre-upgrade database backup together with the matching old image.diff --git a/migrations/versioned/000099_pg_search_0226.up.sql b/migrations/versioned/000099_pg_search_0226.up.sqlnew file mode 100644index 000000000..c1a257d2a--- /dev/null+++ b/migrations/versioned/000099_pg_search_0226.up.sql@@ -0,0 +1,29 @@+-- Complete the SQL side of the validated ParadeDB 0.22.2 -> 0.22.6 image upgrade.+-- Earlier extension migrations do not run again on existing databases.+DO $$+DECLARE+ installed_version TEXT;+BEGIN+ IF current_setting('app.skip_embedding', true) = 'true' THEN+ RETURN;+ END IF;++ SELECT extversion INTO installed_version FROM pg_extension WHERE extname = 'pg_search';++ -- Leave absent extensions and other release lines under operator control.+ -- Do not downgrade a newer extension or upgrade an external server to its+ -- potentially incompatible default version.+ IF installed_version IS NULL OR installed_version NOT IN ('0.22.2', '0.22.3', '0.22.4', '0.22.5') THEN+ RETURN;+ END IF;++ IF NOT EXISTS (+ SELECT 1 FROM pg_available_extension_versions+ WHERE name = 'pg_search' AND version = '0.22.6'+ ) THEN+ RAISE NOTICE 'pg_search 0.22.6 is not available; update the server image and run ALTER EXTENSION pg_search UPDATE TO ''0.22.6'' manually';+ RETURN;+ END IF;++ ALTER EXTENSION pg_search UPDATE TO '0.22.6';+END $$;diff --git a/scripts/test_paradedb_upgrade.py b/scripts/test_paradedb_upgrade.pynew file mode 100644index 000000000..5aa020e37--- /dev/null+++ b/scripts/test_paradedb_upgrade.py@@ -0,0 +1,214 @@+"""Verify a ParadeDB patch upgrade using disposable Docker volumes and real migrations.++Requires Python 3 and Docker; no database credentials or running WeKnora needed.+Run: python3 scripts/test_paradedb_upgrade.py+Artifacts (snapshots, plans, logs and a synthetic-data backup) are kept in /tmp.+"""+import argparse+import hashlib+import json+import pathlib+import random+import subprocess+import tempfile+import time+import uuid++ROOT = pathlib.Path(__file__).resolve().parents[1]+OUT = None+CONTAINER = 'weknora-pdb-upgrade-' + uuid.uuid4().hex[:12]++def sql(query, db='weknora'):+ p = subprocess.run(['docker', 'exec', '-i', CONTAINER, 'psql', '-X', '-qAt', '-U', 'postgres', '-d', db, '-v', 'ON_ERROR_STOP=1'], input=query, text=True, capture_output=True)+ if p.returncode:+ raise RuntimeError(p.stderr)+ return p.stdout.strip()++def quote(s):+ return "'" + s.replace("'", "''") + "'"++def seed():+ rng = random.Random(221226)+ topics = ['数据库 向量 检索 PostgreSQL database search', '知识库 文档 问答 人工智能 retrieval', '北京 上海 深圳 中国 城市', 'Docker 安装 部署 CPU AVX2', '备份 恢复 升级 数据完整性', '权限 租户 共享 用户 authentication']+ stmts = ['BEGIN;', 'TRUNCATE embeddings, tenants, sessions, messages, models, knowledge_bases, knowledges, chunks RESTART IDENTITY CASCADE;']+ queries = {}+ for dim in (798, 1024, 3584):+ for n in range(240):+ vector = '[' + ','.join(f'{rng.uniform(-1, 1):.5f}' for _ in range(dim)) + ']'+ if n in (1, 71, 139):+ queries[f'{dim}_{n}'] = vector+ # Vary term frequency/length; cover NULL, disabled, tags, KB and document filters.+ content = ' '.join([topics[n % 6]] * (1 + n % 7)) + ' ' + ' '.join(rng.choices(topics, k=n % 5))+ enabled = 'NULL' if n % 13 == 0 else ('false' if n % 11 == 0 else 'true')+ stmts.append(f"INSERT INTO embeddings(source_id, source_type, chunk_id, knowledge_id, knowledge_base_id, tag_id, content, dimension, embedding, is_enabled) VALUES ('src-{dim}-{n}',{n % 3},'chunk-{dim}-{n}','doc-{n % 9}','kb-{n % 3}',{quote('tag-'+str(n % 4)) if n % 7 else 'NULL'},{quote(content)},{dim},{quote(vector)},{enabled});")+ stmts += [+ "INSERT INTO tenants(id,name,description,business) VALUES (10101,'升级验证','中文与 emoji 🧪','test');",+ "INSERT INTO sessions(id,tenant_id,title) VALUES ('upgrade-session',10101,'升级前会话');",+ "INSERT INTO messages(id,request_id,session_id,role,content,knowledge_references) VALUES ('upgrade-message','upgrade-request','upgrade-session','assistant','原始回答:数据库检索 🧪','[{\"id\":\"source\",\"score\":0.875}]');",+ "INSERT INTO models(id,tenant_id,name,type,source,parameters) VALUES ('upgrade-model',10101,'fixture','Embedding','remote','{\"dimension\":1024}');",+ "INSERT INTO knowledge_bases(id,tenant_id,name,embedding_model_id,summary_model_id) VALUES ('kb-0',10101,'验证知识库','upgrade-model','');",+ "INSERT INTO knowledges(id,tenant_id,knowledge_base_id,type,title,source,metadata) VALUES ('doc-0',10101,'kb-0','file','中文文档','upload','{\"nested\":{\"value\":42}}');",+ "INSERT INTO chunks(id,tenant_id,knowledge_base_id,knowledge_id,content,chunk_index,start_at,end_at) VALUES ('upgrade-chunk',10101,'kb-0','doc-0','原始分块',0,0,4);",+ 'COMMIT; VACUUM ANALYZE embeddings;',+ ]+ (OUT/'seed.sql').write_text('\n'.join(stmts))+ sql('\n'.join(stmts))+ (OUT/'vectors.json').write_text(json.dumps(queries))+ print('Seeded 720 embeddings plus tenant/model/KB/document/chunk/session/message data', flush=True)++def snapshot(stage):+ tables = sql("SELECT c.relname FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace WHERE n.nspname='public' AND c.relkind IN ('r','p') AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.classid='pg_class'::regclass AND d.objid=c.oid AND d.deptype='e') ORDER BY 1").splitlines()+ data = {}+ for table in tables:+ ident = '"'+table.replace('"','""')+'"'+ rows = sql(f'SELECT to_jsonb(t)::text FROM {ident} t ORDER BY to_jsonb(t)::text')+ data[table] = {'count': int(sql(f'SELECT count(*) FROM {ident}')), 'sha256': hashlib.sha256(rows.encode()).hexdigest()}+ seq = sql("SELECT schemaname,sequencename,start_value,min_value,max_value,increment_by,cycle,last_value FROM pg_sequences WHERE schemaname='public' ORDER BY sequencename")+ schema = sql("SELECT table_name,column_name,data_type,udt_name,is_nullable,column_default FROM information_schema.columns WHERE table_schema='public' ORDER BY table_name,ordinal_position")+ indexes = sql("SELECT c.relname,i.indisvalid,i.indisready,c.relfilenode,pg_get_indexdef(i.indexrelid) FROM pg_index i JOIN pg_class c ON c.oid=i.indexrelid JOIN pg_class t ON t.oid=i.indrelid JOIN pg_namespace n ON n.oid=t.relnamespace WHERE n.nspname='public' ORDER BY c.relname")+ results = {}+ plans = {}+ keyword_queries = ['数据库', '知识库 文档', 'Docker AVX2', 'PostgreSQL database', '北京 上海', '权限 用户', '不存在的关键词xyz', '']+ filters = ['', " AND knowledge_base_id IN ('kb-0','kb-1')", " AND knowledge_base_id='kb-0' AND knowledge_id IN ('doc-0','doc-3')", " AND tag_id IN ('tag-1','tag-2')"]+ # Same |||, scoring and enabled predicate as KeywordsRetrieve. id only resolves equal-score ties.+ for q in keyword_queries:+ for j, filt in enumerate(filters):+ query = f"SELECT id,paradedb.score(id) AS score FROM embeddings WHERE content ||| {quote(q)} AND (is_enabled IS NULL OR is_enabled=true){filt} ORDER BY score DESC,id LIMIT 10"+ key = f'bm25:{q}:{j}'+ results[key] = sql(query)+ plans[key] = sql('EXPLAIN (COSTS OFF) '+query)+ vectors = json.loads((OUT/'vectors.json').read_text())+ for name, vector in vectors.items():+ dim = int(name.split('_')[0])+ for j, filt in enumerate(filters):+ # Exact production candidate expansion, halfvec expression, threshold, and ef_search.+ query = f"SELECT id,1-distance AS score FROM (SELECT id,embedding::halfvec({dim}) <=> {quote(vector)}::halfvec({dim}) AS distance FROM embeddings WHERE dimension={dim} AND (is_enabled IS NULL OR is_enabled=true){filt} ORDER BY embedding::halfvec({dim}) <=> {quote(vector)}::halfvec({dim}) LIMIT 100) candidates WHERE distance<=1.1 ORDER BY distance LIMIT 10"+ key = f'vector:{name}:{j}'+ results[key] = sql('BEGIN; SET LOCAL hnsw.ef_search=100; '+query+'; COMMIT;')+ # Force the index separately so a small fixture cannot silently test only sequential scans.+ results[key+':hnsw'] = sql('BEGIN; SET LOCAL enable_seqscan=off; SET LOCAL enable_bitmapscan=off; SET LOCAL enable_sort=off; SET LOCAL hnsw.ef_search=100; '+query+'; COMMIT;')+ plans[key] = sql('BEGIN; SET LOCAL enable_seqscan=off; SET LOCAL enable_bitmapscan=off; SET LOCAL enable_sort=off; SET LOCAL hnsw.ef_search=100; EXPLAIN (COSTS OFF) '+query+'; COMMIT;')+ assert 'Index Scan using embeddings_embedding_idx_'+str(dim) in plans[key], key+' did not use HNSW'+ assert any('Custom Scan' in p for k,p in plans.items() if k.startswith('bm25:')), 'BM25 index was not used'+ result = {'tables': data, 'sequences': seq, 'schema': schema, 'indexes': indexes, 'queries': results}+ (OUT/(stage+'.json')).write_text(json.dumps(result, ensure_ascii=False, indent=2))+ (OUT/(stage+'-plans.json')).write_text(json.dumps(plans, ensure_ascii=False, indent=2))+ (OUT/(stage+'-versions.txt')).write_text(sql("SELECT version(); SELECT extname,extversion FROM pg_extension ORDER BY 1; SELECT * FROM paradedb.version_info();"))+ print(f'{stage}: {len(data)} tables, {len(results)} retrieval queries captured', flush=True)+ if stage != 'before':+ baseline = json.loads((OUT/'before.json').read_text())+ differences = [key for key in result if result[key] != baseline[key]]+ if differences:+ print('Differences:', differences)+ if 'queries' in differences:+ print([key for key,value in results.items() if baseline['queries'][key] != value])+ raise SystemExit(1)+ print('PASS: rows, columns, sequences, index files, result IDs, ordering and scores unchanged', flush=True)++def docker(*args, **kwargs):+ return subprocess.run(['docker', *args], check=True, capture_output=True, **kwargs)+++def start(image, volume):+ docker('run', '-d', '--name', CONTAINER, '--network', 'none', '--shm-size=512m',+ '-e', 'POSTGRES_PASSWORD=isolated-upgrade-test', '-e', 'POSTGRES_DB=weknora',+ '-v', volume+':/var/lib/postgresql/data', image)+ for _ in range(120):+ # Wait for the final server, not the bootstrap server that only uses a socket.+ ready = subprocess.run(['docker', 'exec', CONTAINER, 'pg_isready', '-h', '127.0.0.1', '-U', 'postgres', '-d', 'weknora'], capture_output=True)+ if ready.returncode == 0:+ return+ time.sleep(1)+ raise RuntimeError('Postgres did not start: '+docker('logs', CONTAINER).stdout.decode())+++def migrate(db, paths, label):+ with (OUT/(label+'.log')).open('w') as log:+ for path in paths:+ log.write(path.name+'\n')+ sql('BEGIN;\n'+path.read_text()+'\nCOMMIT;', db)+ print(f'{label}: {len(paths)} SQL migrations passed', flush=True)+++def check_writes():+ # Committed writes must update both existing BM25 and HNSW indexes.+ vector = '['+','.join(['1']*1024)+']'+ new_id = sql("INSERT INTO embeddings(source_id,source_type,chunk_id,knowledge_id,knowledge_base_id,content,dimension,embedding,is_enabled) VALUES ('post-upgrade',0,'new-chunk','new-doc','new-kb','upgradeuniquetoken',1024,"+quote(vector)+",true) RETURNING id")+ assert sql("SELECT id FROM embeddings WHERE content ||| 'upgradeuniquetoken'") == new_id+ nearest = sql("BEGIN; SET LOCAL enable_seqscan=off; SET LOCAL enable_bitmapscan=off; SET LOCAL enable_sort=off; SELECT id FROM embeddings WHERE dimension=1024 ORDER BY embedding::halfvec(1024) <=> "+quote(vector)+"::halfvec(1024) LIMIT 1; COMMIT;")+ assert nearest == new_id, 'HNSW did not find the newly inserted vector'+ sql("UPDATE embeddings SET content='updateduniquetoken' WHERE id="+new_id)+ assert sql("SELECT count(*) FROM embeddings WHERE content ||| 'upgradeuniquetoken'") == '0'+ assert sql("SELECT id FROM embeddings WHERE content ||| 'updateduniquetoken'") == new_id+ sql('DELETE FROM embeddings WHERE id='+new_id)+ assert sql("SELECT count(*) FROM embeddings WHERE content ||| 'updateduniquetoken'") == '0'+ print('PASS: committed insert/vector lookup/update/delete on existing indexes', flush=True)+++def main():+ global OUT+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument('--output-dir', type=pathlib.Path)+ args = parser.parse_args()+ OUT = args.output_dir or pathlib.Path(tempfile.mkdtemp(prefix='weknora-pdb-upgrade-'))+ OUT.mkdir(parents=True, exist_ok=True)+ if any(OUT.iterdir()):+ raise RuntimeError('Use an empty output directory')+ print('Evidence: '+str(OUT), flush=True)+ volume = CONTAINER+'-data'+ old, new = 'paradedb/paradedb:v0.22.2-pg17', 'paradedb/paradedb:v0.22.6-pg17'+ paths = sorted((ROOT/'migrations/versioned').glob('*.up.sql'))+ baseline = [p for p in paths if int(p.name.split('_')[0]) < 99]+ upgrade = ROOT/'migrations/versioned/000099_pg_search_0226.up.sql'+ # Only resources created by this invocation are ever removed.+ docker('volume', 'create', volume)+ try:+ start(old, volume)+ migrate('weknora', baseline, 'old-migrations')+ assert sql("SELECT extversion FROM pg_extension WHERE extname='pg_search'") == '0.22.2'+ # Older external servers without the target package must remain usable.+ migrate('weknora', [upgrade], 'unavailable-target')+ assert sql("SELECT extversion FROM pg_extension WHERE extname='pg_search'") == '0.22.2'+ seed()+ snapshot('before')+ with (OUT/'before.dump').open('wb') as backup:+ subprocess.run(['docker', 'exec', CONTAINER, 'pg_dump', '-U', 'postgres', '-d', 'weknora', '-Fc'], check=True, stdout=backup)+ docker('stop', '-t', '60', CONTAINER)+ docker('rm', CONTAINER)+ start(new, volume)+ # Replacing the image alone leaves the SQL catalog at the old version.+ assert sql("SELECT extversion FROM pg_extension WHERE extname='pg_search'") == '0.22.2'+ sql("BEGIN; SET LOCAL app.skip_embedding='true';\n"+upgrade.read_text()+"\nCOMMIT;")+ assert sql("SELECT extversion FROM pg_extension WHERE extname='pg_search'") == '0.22.2'+ migrate('weknora', [upgrade, upgrade], 'extension-upgrade-and-idempotence')+ assert sql("SELECT extversion FROM pg_extension WHERE extname='pg_search'") == '0.22.6'+ assert sql('SELECT version FROM paradedb.version_info()') == '0.22.6'+ snapshot('after')+ docker('restart', '-t', '60', CONTAINER)+ for _ in range(60):+ try:+ sql('SELECT 1')+ break+ except RuntimeError:+ time.sleep(1)+ snapshot('after-restart')+ check_writes()+ sql('CREATE DATABASE upgrade_fresh TEMPLATE template0')+ # The new migration must not install pg_search on non-search databases.+ migrate('upgrade_fresh', [upgrade], 'absent-extension')+ assert sql("SELECT count(*) FROM pg_extension WHERE extname='pg_search'", 'upgrade_fresh') == '0'+ migrate('upgrade_fresh', paths, 'fresh-migrations')+ assert sql("SELECT extversion FROM pg_extension WHERE extname='pg_search'", 'upgrade_fresh') == '0.22.6'+ sql("INSERT INTO embeddings(source_id,source_type,content,dimension) VALUES ('fresh',0,'新安装检索',1024)", 'upgrade_fresh')+ assert sql("SELECT count(*) FROM embeddings WHERE content ||| '检索'", 'upgrade_fresh') == '1'+ print('PASS: fresh install and Chinese BM25 query', flush=True)+ (OUT/'PASS').write_text('Upgrade, restart, data integrity, retrieval, writes and fresh install passed.\n')+ finally:+ logs = subprocess.run(['docker', 'logs', CONTAINER], capture_output=True)+ (OUT/'postgres.log').write_bytes(logs.stdout+logs.stderr)+ subprocess.run(['docker', 'rm', '-f', CONTAINER], capture_output=True)+ docker('volume', 'rm', volume)+++if __name__ == '__main__':+ main()diff --git a/website-docs/01-getting-started/02-installation.md b/website-docs/01-getting-started/02-installation.mdindex 35dbf5918..638ce9f3e 100644--- a/website-docs/01-getting-started/02-installation.md+++ b/website-docs/01-getting-started/02-installation.md@@ -44,6 +44,8 @@ flowchart TB- **源码编译**:Go 1.26(见 `docker/Dockerfile.app` builder 阶段 `golang:1.26-bookworm`)、CGO(依赖 `libsqlite3-dev`)、Node.js + npm(前端)、Python 3.10 + uv(docreader)。- **Kubernetes**:>= 1.25.0(`helm/Chart.yaml`)。+Compose 默认 ParadeDB `v0.22.6-pg17` 的 x86 CPU 基线为 `x86-64-v2`(包括 SSE4.2、POPCNT),不再强制要求 AVX2。这不代表所有 ARM CPU 或其他可选服务均兼容。+## 一、Docker Compose 标准部署(docker-compose.yml)最快路径:@@ -68,6 +70,8 @@ docker compose ps # 等所有服务变成 healthy/running若已有部署并下载了更新的 release:+> 如果数据库仍为 ParadeDB `v0.22.2-pg17`,先按 [ParadeDB 升级说明](https://github.com/Tencent/WeKnora/blob/main/docs/paradedb-upgrade.md) 停止写入、备份、保留数据卷更换镜像并完成 `pg_search` 扩展升级,再恢复应用。仅替换镜像不会更新已有数据库的扩展 SQL;迁移 `000099` 会处理 WeKnora 库中符合条件的 `0.22.2–0.22.5`,其他数据库仍需单独检查。+```bash# 在 .env 中将 WEKNORA_VERSION 设为目标版本(如 0.7.0),或保持 latestdocker compose pull@@ -83,7 +87,7 @@ docker compose up -d| `frontend` | `wechatopenai/weknora-ui:${WEKNORA_VERSION:-latest}` | `${FRONTEND_PORT:-80}:80` | app(healthy) | Nginx 托管 SPA 并反代到 app;`APP_HOST`/`APP_BACKEND_PORT`/`APP_SCHEME` 可指向远程后端 || `app` | `wechatopenai/weknora-app` | `${APP_PORT:-8080}:8080` | postgres(healthy)、redis、docreader(healthy) | Go 后端;挂载 `./config/config.yaml`、`data-files` 卷;健康检查 `GET /health` || `docreader` | `wechatopenai/weknora-docreader` | 仅 `expose: 50051`(不发布到宿主机) | — | 文档解析 gRPC 服务;健康检查 `grpc_health_probe`;与 app 共享 `docreader-tmp` 卷传递图片 |-| `postgres` | `paradedb/paradedb:v0.22.2-pg17` | 不映射宿主端口 | — | ParadeDB = PostgreSQL 17 + BM25/向量扩展,默认检索引擎 |+| `postgres` | `paradedb/paradedb:v0.22.6-pg17` | 不映射宿主端口 | — | ParadeDB = PostgreSQL 17 + BM25/向量扩展,默认检索引擎 || `redis` | `redis:7.0-alpine` | 不映射宿主端口 | — | `--appendonly yes --requirepass ${REDIS_PASSWORD}` |### 可选服务与 profilesdiff --git a/website-docs/02-architecture/01-overview.md b/website-docs/02-architecture/01-overview.mdindex a0124d4c8..753b44349 100644--- a/website-docs/02-architecture/01-overview.md+++ b/website-docs/02-architecture/01-overview.md@@ -13,7 +13,7 @@ WeKnora 采用"主服务 + 前端 + 文档解析微服务"的三进程核心架| `app` | `wechatopenai/weknora-app`(`docker/Dockerfile.app`,Go) | `8080` | 主后端:REST API、RAG 检索、Agent 引擎、异步任务 worker、IM/Embed 渠道接入。健康检查 `GET /health` || `frontend` | `wechatopenai/weknora-ui`(`frontend/`,NGINX + Vue3 静态产物) | `80` | Web UI;NGINX 同时充当反向代理,将 `/api` 转发到 `app`(`APP_HOST`/`APP_BACKEND_PORT`/`APP_SCHEME` 可指向远端后端) || `docreader` | `wechatopenai/weknora-docreader`(`docker/Dockerfile.docreader`,Python) | `50051`(仅 compose 网络内 expose,不映射宿主机) | 文档解析微服务:gRPC 服务端,PDF/DOCX/Excel/EPUB/网页等 25+ 格式解析与页面渲染。健康检查 `grpc_health_probe` |-| `postgres` | `paradedb/paradedb:v0.22.2-pg17` | `5432`(网络内) | 主数据库。ParadeDB 发行版自带 BM25 全文检索与 pgvector 向量能力,因此**默认部署无需独立向量库**(`RETRIEVE_DRIVER=postgres`) |+| `postgres` | `paradedb/paradedb:v0.22.6-pg17` | `5432`(网络内) | 主数据库。ParadeDB 发行版自带 BM25 全文检索与 pgvector 向量能力,因此**默认部署无需独立向量库**(`RETRIEVE_DRIVER=postgres`) || `redis` | `redis:7.0-alpine`(`appendonly` + `requirepass`) | `6379`(网络内) | Asynq 任务队列、SSE 流管理(跨实例)、system_settings 发布订阅、限流与分布式模型并发闸门 || `sandbox` | `wechatopenai/weknora-sandbox`(`docker/Dockerfile.sandbox`) | — | WeKnora 标准运行镜像;可直接用于空间 Docker 后端,接入 CubeSandbox/E2B 时则通过模板 API 自动注册并用于 Agent Skills |diff --git a/website-docs/06-development/01-dev-guide.md b/website-docs/06-development/01-dev-guide.mdindex 4782faf22..fea4742a0 100644--- a/website-docs/06-development/01-dev-guide.md+++ b/website-docs/06-development/01-dev-guide.md@@ -64,7 +64,7 @@ make dev-restart # 重启| 服务 | 镜像 | 端口(默认) | 启动条件 || --- | --- | --- | --- |-| `postgres` | `paradedb/paradedb:v0.22.2-pg17`(自带 pg_search/BM25) | `5432` | 默认启动 |+| `postgres` | `paradedb/paradedb:v0.22.6-pg17`(自带 pg_search/BM25) | `5432` | 默认启动 || `redis` | `redis:7.0-alpine`(`--requirepass`) | `6379` | 默认启动 || `docreader` | 本地构建 `docker/Dockerfile.docreader` | `50051`(gRPC) | 默认启动 || `searxng`(+`searxng-init`) | `searxng/searxng:latest` | `127.0.0.1:8888` | `--searxng` / `--full`(compose profile `searxng`) |diff --git a/website-docs/06-development/02-database-schema.md b/website-docs/06-development/02-database-schema.mdindex c57007720..9bdd5c60f 100644--- a/website-docs/06-development/02-database-schema.md+++ b/website-docs/06-development/02-database-schema.md@@ -8,7 +8,7 @@ WeKnora 使用版本化迁移维护数据库结构,PostgreSQL 与 SQLite 分| `DB_DRIVER` | 说明 || --- | --- |-| `postgres` | 标准模式。既支持原生 PostgreSQL(+pgvector),也支持 **ParadeDB**(PostgreSQL 分支,内置 `pg_search`/BM25,官方 compose 默认镜像 `paradedb/paradedb:v0.22.2-pg17`)。GORM DSN 由 `DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME` 拼装,强制 `sslmode=disable`、`TimeZone=UTC` |+| `postgres` | 标准模式。既支持原生 PostgreSQL(+pgvector),也支持 **ParadeDB**(PostgreSQL 分支,内置 `pg_search`/BM25,官方 compose 默认镜像 `paradedb/paradedb:v0.22.6-pg17`)。GORM DSN 由 `DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME` 拼装,强制 `sslmode=disable`、`TimeZone=UTC` || `sqlite` | Lite 模式。路径取 `DB_PATH`(默认 `./data/weknora.db`),DSN 附加 `_journal_mode=WAL&_busy_timeout=5000&_foreign_keys=on`,并加载 `sqlite-vec` 扩展(`sqlite_vec.Auto()`)做向量检索 || 其他值 | 直接报错 `unsupported database driver` |