Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(docker): upgrade ParadeDB for CPUs without AVX2

wizardchenfa56b5b9322f
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 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-pg17
container_name: WeKnora-postgres-dev
ports:
- "${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-pg17
container_name: WeKnora-langfuse-db-init-dev
depends_on:
postgres:
diff --git a/docker-compose.yml b/docker-compose.yml
index 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-pg17
container_name: WeKnora-postgres
environment:
- 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-pg17
container_name: WeKnora-langfuse-db-init
depends_on:
postgres:
diff --git a/docs/paradedb-upgrade.md b/docs/paradedb-upgrade.md
new file mode 100644
index 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.sql
new file mode 100644
index 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.sql
new file mode 100644
index 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.py
new file mode 100644
index 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.md
index 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),或保持 latest
docker 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}` |
### 可选服务与 profiles
diff --git a/website-docs/02-architecture/01-overview.md b/website-docs/02-architecture/01-overview.md
index 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.md
index 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.md
index 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` |