Atari Legacy Magazine 是一個帶有明顯懷舊屬性的數字歸檔項目它的目標不是簡單做一份文章列表而是把關于 Atari 的老雜志、機種評測、游戲攻略和訪談資料通過結構化的方式保存下來并讓讀者能按年份、主題、雜志名快速檢索。實際動手時這個項目牽扯到的并不只是“寫個網頁”而是版權確認、掃描件管理、元數據建模、OCR 文本化、全文索引和部署維護這一整條鏈路。接下來的內容會圍繞 Atari Legacy Magazine 的搭建過程從需求拆解開始使用 Flask 和 SQLite 逐步完成一個最小可用的雜志歸檔系統。1. 先拆需求別把懷舊歸檔站做成簡單的 PDF 列表1.1 這個項目解決什么問題為什么不能只放 PDF把老雜志數字化之后最常見的做法是建一個目錄把 PDF 文件按年份和期次放進去再寫一個靜態頁面列出來。這種方案對個人備份夠用但它解決的問題是“文件能被找到”而不是“內容能被使用”。Atari Legacy Magazine 這類項目的核心價值是內容組織。一本雜志里通常有編輯寄語、新機評測、游戲攻略、玩家來信、廠商廣告等多個欄目。讀者搜索時往往不是想找“1980 年 1 月這一期”而是想找“所有提到 Pong 的文章”“某位作者寫過的 Atari 400 評測”“某個硬件的價格表”。如果不把期次拆到文章粒度不把 OCR 后的文本保存下來這些需求都做不了。所以這個項目最少要完成三件事保存原始文件包括封面掃描件、內頁掃描件或 PDF。為每一篇文章建立元數據包括標題、作者、頁碼、摘要、標簽。對文章正文做全文索引讓用戶能跨期次、跨雜志搜索。PDF 是原始資料但在業務模型里只能算文件載體。更合理的模型是雜志是出版物的集合期次是雜志的一本文章是期次里的內容單元標簽是跨期次的內容維度。1.2 核心功能拆分與最小可用范圍在動手寫代碼前可以先把功能分成“必須做”“先不做”“以后擴展”三類。這樣能避免項目一開始就陷入復雜的后臺管理、權限系統或自動采集任務。功能是否優先說明雜志、期次、文章數據管理優先系統的基礎結構沒有這些就沒有瀏覽和檢索掃描件和封面文件存儲優先至少要約定目錄規則避免文件亂放文章正文全文檢索優先區分普通列表和知識庫的關鍵能力按年份、標簽篩選優先讓檢索結果能按期刊背景縮小范圍管理后臺先不做可以用命令行導入腳本代替OCR 自動任務先做簡化版先離線生成文本文件再手動導入用戶評論、收藏、賬號體系暫緩對歸檔站不是核心后期可擴展最小可用范圍可以定義為一套命令行導入流程加三個頁面首頁列出所有雜志雜志詳情頁列出期次搜索頁返回文章列表。再加上一個后臺接口用于返回 JSON 格式的搜索結果。完成這個閉環后再逐步增加管理界面和自動流程。1.3 技術選型為什么用 Flask SQLite FTS5 起步Atari Legacy Magazine 的典型使用場景是個人或小團隊維護的專題網站數據量在幾萬到幾十萬篇文章之間并發訪問不會太高。這種場景不需要一開始就上重型數據庫和微服務架構用 Flask 加 SQLite 可以更快跑通。方案適合場景優點劣勢Flask SQLite FTS5個人歸檔站、低并發工具站點環境簡單SQLite 單文件易備份FTS5 原生支持全文檢索高并發寫入能力弱復雜管理后臺要自己實現Django PostgreSQL多作者內容平臺、管理后臺重ORM 和 Admin 生態成熟PostgreSQL 全文檢索能力強項目結構偏重初期開發成本高Next.js PostgreSQL偏前端交互的社區展示站前后端一體交互體驗好需要同時維護 Node 服務和數據庫部署鏈路更長Spring Boot MySQL大型團隊、企業級平臺生態完善適合多人協作對個人歸檔項目過重SQLite 在低并發讀多寫少的場景下足夠穩定而且一個.db文件可以直接復制備份。FTS5 是 SQLite 自帶的全文索引模塊適合英文和大多數按空格分詞的文本。如果后期要處理大量中文內容可以再引入分詞表或者把文本遷移到 PostgreSQL 的 tsvector。先選輕量方案不等于鎖死架構。2. 環境準備與項目結構先把依賴固定下來2.1 Python 環境和依賴清單這個項目使用 Python 3.10 以上版本建議先創建虛擬環境再安裝依賴。以下命令適用于 LinuxmacOS 和 Windows 的激活命令略有差異。python3 -m venv .venv source .venv/bin/activate python --version pip install -U pip在項目根目錄創建requirements.txt示例內容如下Flask3.0.3 requests2.32.3 beautifulsoup44.12.3 PyYAML6.0.2 gunicorn22.0.0其中 Flask 用于 Web 服務requests 和 beautifulsoup4 用于后續采集或解析 HTML 元數據PyYAML 用來讀取導入腳本的元數據文件gunicorn 在部署階段啟動服務。版本號是示例落地前要結合當前 Python 環境確認兼容性建議鎖定版本后寫入 requirements。安裝依賴pip install -r requirements.txt需要注意如果只需要跑通基本功能requests 和 beautifulsoup4 可以暫時不裝。但一旦準備做自動采集就會用到它們。為了避免后面反復改依賴先把常用依賴放進去。2.2 項目目錄結構推薦使用如下目錄結構把數據文件、模板、靜態資源和導入腳本分開。atari-legacy-magazine/ ├── app.py ├── config.py ├── init_db.py ├── import_legacy.py ├── schema.sql ├── requirements.txt ├── data/ │ ├── meta/ │ │ └── sample.yaml │ └── scans/ │ └── atari-legacy/ │ └── 1980-01.pdf ├── static/ │ ├── css/ │ ├── img/ │ ├── covers/ │ └── js/ └── templates/ ├── base.html ├── index.html ├── magazine_detail.html ├── issue_detail.html ├── article_detail.html └── search.htmldata/meta存放每期雜志的元數據文件data/scans存放原始掃描件和 PDF。schema.sql用于初始化數據庫init_db.py執行該文件import_legacy.py負責把元數據寫入數據庫。Web 層只負責查詢和渲染這樣導入與瀏覽邏輯能互相隔離。2.3 初始化數據庫和基礎配置在config.py中定義數據庫路徑和文件目錄盡量讓路徑通過環境變量覆蓋方便測試環境與生產環境切換。import os BASE_DIR os.path.dirname(os.path.abspath(__file__)) DATABASE os.environ.get( ATARI_DB, os.path.join(BASE_DIR, data, legacy.db) ) SCAN_DIR os.environ.get( ATARI_SCAN_DIR, os.path.join(BASE_DIR, data, scans) ) COVER_DIR os.environ.get( ATARI_COVER_DIR, os.path.join(BASE_DIR, static, covers) ) DEBUG os.environ.get(ATARI_DEBUG, true).lower() true在app.py中實現一個連接 SQLite 的輔助函數每請求獲取連接用完關閉。import sqlite3 from flask import Flask, g from config import DATABASE, DEBUG app Flask(__name__) app.config[DATABASE] DATABASE app.config[DEBUG] DEBUG def get_db(): if db not in g: g.db sqlite3.connect( app.config[DATABASE], detect_typessqlite3.PARSE_DECLTYPES, ) g.db.row_factory sqlite3.Row g.db.execute(PRAGMA foreign_keys ON) return g.db app.teardown_appcontext def close_db(error): db g.pop(db, None) if db is not None: db.close()init_db.py讀取schema.sql并執行。為了后續方便可以用命令行參數指定數據庫位置。import sqlite3 import sys from config import DATABASE def init_db(db_path): conn sqlite3.connect(db_path) with open(schema.sql, r, encodingutf-8) as f: conn.executescript(f.read()) conn.commit() conn.close() if __name__ __main__: db_path sys.argv[1] if len(sys.argv) 1 else DATABASE init_db(db_path) print(fdatabase initialized: {db_path})執行初始化后會在data目錄下生成legacy.db。mkdir -p data python init_db.py這一步如果報錯先檢查data目錄是否存在以及 Python 是否有權限寫入當前目錄。3. 數據建模雜志、期次、文章和標簽的關系3.1 實體關系與字段設計核心模型可以拆成四張業務表加一張關聯表。表名用途關鍵字段magazines雜志名稱和出版信息id, name, publisher, start_year, end_year, descriptionissues某一期雜志id, magazine_id, issue_number, title, published_on, cover_path, pdf_patharticles期次內的文章id, issue_id, title, author, page_start, page_end, summary, ocr_texttags標簽id, namearticle_tags文章與標簽的多對多關聯article_id, tag_id把雜志和期次分開是因為一本雜志有多期每一期有自己的出版日期、封面文件和 PDF 文件。把文章和期次分開是因為文章是檢索的最小單位。如果只保存“某一期 PDF”搜索時無法定位到具體頁也無法按文章展示結果。字段設計時要注意published_on使用 ISO 格式的日期字符串例如1980-01-15方便比較和排序。page_start和page_end是整數用于文章切分和 OCR 文本按頁導入。ocr_text是長文本字段內容來自掃描件的文字識別結果可能包含大量換行和噪聲。標簽使用多對多關聯因為一篇文章可能有“Atari 400”“游戲評測”“1980”等多個主題標簽。3.2 建表 SQL 與 SQLite 約束schema.sql示例PRAGMA foreign_keys ON; CREATE TABLE IF NOT EXISTS magazines ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL UNIQUE, publisher TEXT, start_year INTEGER, end_year INTEGER, description TEXT ); CREATE TABLE IF NOT EXISTS issues ( id INTEGER PRIMARY KEY AUTOINCREMENT, magazine_id INTEGER NOT NULL, issue_number TEXT NOT NULL, title TEXT NOT NULL, published_on TEXT, cover_path TEXT, pdf_path TEXT, FOREIGN KEY (magazine_id) REFERENCES magazines(id) ON DELETE CASCADE, UNIQUE (magazine_id, issue_number) ); CREATE TABLE IF NOT EXISTS articles ( id INTEGER PRIMARY KEY AUTOINCREMENT, issue_id INTEGER NOT NULL, title TEXT NOT NULL, author TEXT, page_start INTEGER, page_end INTEGER, summary TEXT, ocr_text TEXT, FOREIGN KEY (issue_id) REFERENCES issues(id) ON DELETE CASCADE ); CREATE TABLE IF NOT EXISTS tags ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL UNIQUE ); CREATE TABLE IF NOT EXISTS article_tags ( article_id INTEGER NOT NULL, tag_id INTEGER NOT NULL, PRIMARY KEY (article_id, tag_id), FOREIGN KEY (article_id) REFERENCES articles(id) ON DELETE CASCADE, FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE ); CREATE INDEX IF NOT EXISTS idx_issues_magazine_id ON issues(magazine_id); CREATE INDEX IF NOT EXISTS idx_articles_issue_id ON articles(issue_id); CREATE INDEX IF NOT EXISTS idx_articles_title ON articles(title);這里的UNIQUE (magazine_id, issue_number)用來防止同一本雜志導入重復期次。ON DELETE CASCADE保證刪除雜志后相關期次和文章一起刪除避免數據庫里出現孤兒數據。使用 SQLite 時外鍵約束默認是關閉的所以連接數據庫后要執行PRAGMA foreign_keys ON。這在前面get_db()中已經加入但導入腳本里也要記得執行否則刪除父記錄時子記錄可能仍然殘留。3.3 啟用 SQLite FTS5 全文索引articles 表使用普通LIKE查詢做關鍵詞搜索在大數據量下會非常慢也無法按相關性排序。SQLite 從 3.9 開始支持 FTS5 全文索引適合這個規模的項目。創建 FTS5 虛擬表并讓它的內容和 articles 表保持同步CREATE VIRTUAL TABLE IF NOT EXISTS fts_articles USING fts5( title, summary, body, author, contentarticles, content_rowidid, tokenizeporter unicode61 ); CREATE TRIGGER IF NOT EXISTS fts_articles_ai AFTER INSERT ON articles BEGIN INSERT INTO fts_articles(rowid, title, summary, body, author) VALUES (new.id, new.title, new.summary, new.ocr_text, new.author); END; CREATE TRIGGER IF NOT EXISTS fts_articles_ad AFTER DELETE ON articles BEGIN INSERT INTO fts_articles(fts_articles, rowid, title, summary, body, author) VALUES (delete, old.id, old.title, old.summary, old.ocr_text, old.author); END; CREATE TRIGGER IF NOT EXISTS fts_articles_au AFTER UPDATE ON articles BEGIN INSERT INTO fts_articles(fts_articles, rowid, title, summary, body, author) VALUES (delete, old.id, old.title, old.summary, old.ocr_text, old.author); INSERT INTO fts_articles(rowid, title, summary, body, author) VALUES (new.id, new.title, new.summary, new.ocr_text, new.author); END;使用contentarticles方式創建外部內容表后FTS5 不復制原文到虛擬表只保存索引節省空間。觸發器負責在新增、刪除、更新文章時同步索引。需要特別說明FTS5 默認的unicode61分詞器按空格和標點切分適合英文資料。如果資料是中文這種分詞方式會把整句話當成一個 token導致檢索效果很差。中文本地化通常需要額外建一個分詞字段例如在導入時用 jieba 生成關鍵詞字符串再放到 FTS5 表里。對于 Atari Legacy Magazine 的英文原版掃描件場景當前配置已經可用。4. 數據導入從掃描件到可檢索文章4.1 文件目錄約定和元數據清單導入流程的第一步不是寫代碼而是把掃描件和元數據文件組織好。目錄命名要穩定建議按“雜志名/年份/期號”組織。data/scans/atari-legacy/1980/1980-01.pdf data/scans/atari-legacy/1980/1980-01-cover.jpg data/scans/atari-legacy/1980/1980-01-page-08.png data/scans/atari-legacy/1980/1980-01-page-09.png元數據文件建議放在獨立目錄使用 YAML 格式便于人工維護。一個元數據文件對應一期雜志。magazine: Atari Legacy issue_number: 1980-01 title: January 1980 published_on: 1980-01-15 cover: covers/atari-legacy-1980-01.jpg pdf: scans/atari-legacy/1980/1980-01.pdf articles: - title: Pong and Beyond: The Early Years author: John Doe page_start: 8 page_end: 14 summary: A short history of Pong and its influence on home consoles. tags: [Pong, History, Arcade] - title: Atari 400 Review author: Jane Smith page_start: 16 page_end: 22 summary: Hands-on review of the Atari 400 computer. tags: [Atari 400, Review, Hardware]命名規范的作用是讓導入腳本能夠按路徑推斷期次同時讓 YAML 文件與掃描件一一對應。如果目錄隨意命名腳本里就要寫大量判斷邏輯而且很容易在重新導入時產生重復數據。4.2 用 Python 腳本讀取目錄并寫入數據庫import_legacy.py的核心思路是讀取--meta目錄下所有 YAML 文件對每個文件檢查雜志、期次是否已存在再插入文章和標簽。腳本需要支持重復執行因此插入前先查詢是否已存在。import argparse import os import sqlite3 import yaml from config import DATABASE def connect(db_path): conn sqlite3.connect(db_path) conn.row_factory sqlite3.Row conn.execute(PRAGMA foreign_keys ON) return conn def get_or_create_magazine(conn, name): cur conn.execute( SELECT id FROM magazines WHERE name ?, (name,) ) row cur.fetchone() if row: return row[id] cur conn.execute( INSERT INTO magazines(name) VALUES (?), (name,) ) return cur.lastrowid def get_or_create_issue(conn, magazine_id, issue_number, title, published_on, cover_path, pdf_path): cur conn.execute( SELECT id FROM issues WHERE magazine_id ? AND issue_number ?, (magazine_id, issue_number), ) row cur.fetchone() if row: return row[id] cur conn.execute( INSERT INTO issues(magazine_id, issue_number, title, published_on, cover_path, pdf_path) VALUES (?, ?, ?, ?, ?, ?) , (magazine_id, issue_number, title, published_on, cover_path, pdf_path), ) return cur.lastrowid def import_yaml_file(conn, meta_path): with open(meta_path, r, encodingutf-8) as f: meta yaml.safe_load(f) magazine_id get_or_create_magazine(conn, meta[magazine]) issue_id get_or_create_issue( conn, magazine_id, meta[issue_number], meta[title], meta.get(published_on), meta.get(cover), meta.get(pdf), ) for article in meta.get(articles, []): cur conn.execute( INSERT INTO articles(issue_id, title, author, page_start, page_end, summary, ocr_text) VALUES (?, ?, ?, ?, ?, ?, ?) , ( issue_id, article[title], article.get(author), article.get(page_start), article.get(page_end), article.get(summary), article.get(ocr_text, ), ), ) article_id cur.lastrowid for tag_name in article.get(tags, []): cur conn.execute( SELECT id FROM tags WHERE name ?, (tag_name,) ) row cur.fetchone() if row: tag_id row[id] else: cur conn.execute( INSERT INTO tags(name) VALUES (?), (tag_name,) ) tag_id cur.lastrowid conn.execute( INSERT OR IGNORE INTO article_tags(article_id, tag_id) VALUES (?, ?), (article_id, tag_id), ) def main(): parser argparse.ArgumentParser(descriptionimport legacy magazine metadata) parser.add_argument(--meta, defaultdata/meta, helpmetadata directory) parser.add_argument(--db, defaultDATABASE, helpsqlite database path) args parser.parse_args() conn connect(args.db) try: for filename in sorted(os.listdir(args.meta)): if not filename.endswith((.yaml, .yml)): continue meta_path os.path.join(args.meta, filename) print(fimporting {meta_path}) import_yaml_file(conn, meta_path) conn.commit() print(import finished) except Exception: conn.rollback() raise finally: conn.close() if __name__ __main__: main()這段代碼的關鍵點有三個標簽不存在時先插入再建立關聯。使用INSERT OR IGNORE避免重復關聯。整個目錄導入過程放在一個事務里一旦發現 YAML 格式錯誤或數據庫約束沖突就回滾整個批次避免導入一半導致數據不完整。4.3 OCR 文本入庫與后續清洗元數據中的ocr_text不是必須手動填寫。更常見的做法是先離線用 OCR 工具識別掃描件再把識別結果寫入 YAML 文件或單獨文本文件。以下片段說明 Tesseract 的調用思路實際使用時需要結合本地環境和圖片路徑。# 需要額外安裝 pytesseract 和 Pillow # import pytesseract # from PIL import Image # page Image.open(data/scans/atari-legacy/1980/1980-01-page-08.png) # text pytesseract.image_to_string(page, langeng)OCR 識別結果往往包含大量換行、頁眉頁腳和識別錯誤。建議導入前做兩步清洗刪除每頁單獨識別時出現的重復頁眉頁腳。根據page_start和page_end把文本切到對應文章下不要讓整期雜志的文本混在一起。如果文章跨頁需要在腳本中按頁拼接。簡單實現可以讀取從page_start到page_end的所有頁面文本用換行連接后寫入ocr_text。注意OCR 和入庫存量文件都涉及版權。不要對沒有授權或自己無權的掃描件做公開上線內部整理也要注明來源公開發布前必須有明確的版權許可。5. 瀏覽與搜索的后端實現5.1 瀏覽頁面的路由設計瀏覽頁面至少需要四個路由首頁、雜志詳情、期次詳情、文章詳情。路由通過 URL 中的整數 ID 定位數據返回 HTML 模板。from flask import render_template app.route(/) def index(): db get_db() rows db.execute( SELECT m.id, m.name, m.publisher, m.start_year, m.end_year, m.description, COUNT(DISTINCT i.id) AS issue_count FROM magazines m LEFT JOIN issues i ON i.magazine_id m.id GROUP BY m.id ORDER BY m.name ).fetchall() return render_template(index.html, magazinesrows) app.route(/magazines/int:magazine_id) def magazine_detail(magazine_id): db get_db() magazine db.execute( SELECT * FROM magazines WHERE id ?, (magazine_id,) ).fetchone() issues db.execute( SELECT id, issue_number, title, published_on, cover_path FROM issues WHERE magazine_id ? ORDER BY published_on , (magazine_id,), ).fetchall() return render_template(magazine_detail.html, magazinemagazine, issuesissues)使用sqlite3.Row之后模板里可以用magazine.name的方式訪問字段比數字下標更直觀。每個路由都要對“數據不存在”的情況做處理否則用戶訪問不存在的 ID 會得到一個 500 錯誤更合理的是返回 404。5.2 搜索結果接口FTS5 排名和分頁搜索接口設計成/api/search返回 JSON方便前端頁面在輸入框中異步請求。搜索核心是 FTS5 的MATCH查詢。from flask import jsonify, request app.route(/api/search) def search_api(): db get_db() q request.args.get(q, ).strip() page max(1, request.args.get(page, 1, typeint)) per_page min(20, max(1, request.args.get(per_page, 10, typeint))) if not q: return jsonify({error: missing q, total: 0, items: []}), 400 search_query q.replace(, ) count_sql SELECT COUNT(*) FROM fts_articles WHERE fts_articles MATCH ? total db.execute(count_sql, (search_query,)).fetchone()[0] data_sql SELECT a.id, a.title, a.author, a.page_start, a.page_end, a.summary, a.issue_id, i.title AS issue_title, i.issue_number, i.published_on, m.name AS magazine_name, bm25(fts_articles) AS rank FROM fts_articles JOIN articles a ON a.id fts_articles.rowid JOIN issues i ON i.id a.issue_id JOIN magazines m ON m.id i.magazine_id WHERE fts_articles MATCH ? ORDER BY rank LIMIT ? OFFSET ? items db.execute( data_sql, (search_query, per_page, (page - 1) * per_page), ).fetchall() return jsonify({ q: q, total: total, page: page, per_page: per_page, items: [dict(row) for row in items], })這里有一個容易被忽略的坑FTS5 的MATCH查詢語法里引號、括號、AND、OR、NOT 都有特殊含義。如果用戶輸入Pong OR History會被當成布爾查詢。如果不希望用戶使用復雜語法可以對輸入做更嚴格的清洗比如只保留字母數字和空格或者把整個輸入包成短語查詢。上面的示例做了一層轉義實際項目還要根據預期行為決定是否允許布爾語法。bm25(fts_articles)是 SQLite 內置的相關性排序函數數值越小表示越相關所以ORDER BY rank默認會把最相關的結果排前面。5.3 篩選年份與標簽搜索接口還需要支持按年份和標簽過濾。年份可以從published_on字段中截取標簽要通過article_tags和tags表關聯。year request.args.get(year, typeint) tag request.args.get(tag, ).strip() conditions [fts_articles MATCH ?] params [search_query] if year: conditions.append(substr(i.published_on, 1, 4) ?) params.append(str(year)) if tag: conditions.append( EXISTS ( SELECT 1 FROM article_tags at JOIN tags t ON t.id at.tag_id WHERE at.article_id a.id AND t.name ? ) ) params.append(tag) where_sql AND .join(conditions)過濾條件全部使用參數綁定不要用字符串拼接。年份字段如果沒填或格式不對substr可能得不到預期結果所以發請求前要在前端做基礎校驗后端也要對year做范圍限制。6. 頁面模板與交互6.1 首頁雜志封面網格首頁通過index.html展示所有雜志。模板繼承自base.html這里只給出關鍵片段。div classmagazine-grid {% for item in magazines %} a classmagazine-card href{{ url_for(magazine_detail, magazine_iditem.id) }} {% if item.cover %} img src{{ url_for(static, filenamecovers/ item.cover) }} alt{{ item.name }} {% else %} div classcover-placeholder{{ item.name }}/div {% endif %} h2{{ item.name }}/h2 p{{ item.publisher }} · {{ item.issue_count }} issues/p /a {% endfor %} /div使用url_for生成 URL可以避免硬編碼路徑。封面圖統一放在static/covers目錄如果沒有封面就顯示占位塊。模板里要注意圖片路徑拼寫大小寫不一致經常導致圖片不顯示。6.2 文章詳情頁展示 OCR 全文與元數據文章詳情頁把文章的 OCR 文本展示出來同時顯示所屬雜志、期次、作者和頁碼。OCR 文本是純文本不要用safe過濾器直接渲染成 HTML因為識別結果可能包含類似和的字符容易造成頁面錯亂也可能帶來 XSS 風險。{% extends base.html %} {% block content %} h1{{ article.title }}/h1 p classmeta {{ magazine.name }} / {{ issue.title }} · {{ article.author or Unknown }} · page {{ article.page_start }}-{{ article.page_end }} /p {% if article.summary %} p classsummary{{ article.summary }}/p {% endif %} article classarticle-content pre{{ article.ocr_text }}/pre /article {% endblock %}使用pre可以保留 OCR 文本原有的換行和縮進比手動替換換行符更安全。頁面樣式上可以給.article-content設置適中的行高和最大寬度避免長文本行過寬影響閱讀。6.3 搜索框與前端防抖搜索頁面可以單獨放在search.html也可以把搜索框放在導航欄輸入時動態請求/api/search。為了避免每次按鍵都請求接口前端加入 300ms 防抖。let timer null; document.querySelector(#search-input).addEventListener(input, function (e) { clearTimeout(timer); const q e.target.value.trim(); if (q.length 2) { document.querySelector(#search-results).innerHTML ; return; } timer setTimeout(() { fetchResults(q); }, 300); }); async function fetchResults(q) { const resp await fetch(/api/search?q${encodeURIComponent(q)}); const data await resp.json(); renderResults(data); } function renderResults(data) { const container document.querySelector(#search-results); if (!data.items || data.items.length 0) { container.innerHTML pNo results/p; return; } const html data.items.map((item) div classsearch-item h3a href/articles/${item.id}${item.title}/a/h3 p${item.magazine_name} · ${item.issue_title} · ${item.author || Unknown}/p /div ).join(); container.innerHTML html; }前端渲染結果時標題是通過模板字符串直接插入 HTML 的。如果數據來自可信的數據庫風險較低但如果未來引入用戶生成內容必須改用 DOM API 或轉義函數。搜索請求中的encodeURIComponent是必需的否則搜索詞里包含、等字符時URL 會被截斷或產生錯誤參數。7. 運行驗證、常見坑和排查路徑7.1 從空庫到可搜索站的完整驗證流程在完成代碼和元數據文件后按以下順序運行可以驗證整個鏈路是否通# 1. 初始化數據庫 mkdir -p data python init_db.py # 2. 導入一期示例數據 python import_legacy.py --meta data/meta --db data/legacy.db # 3. 啟動開發服務器 flask --app app.py run --debug # 4. 在另一個終端請求搜索接口 curl http://127.0.0.1:5000/api/search?qPong如果一切正常curl會返回一段 JSON包含total和items。例如{ q: Pong, total: 1, page: 1, per_page: 10, items: [ { id: 1, title: Pong and Beyond: The Early Years, author: John Doe, page_start: 8, page_end: 14, issue_title: January 1980, magazine_name: Atari Legacy } ] }驗證時要同時檢查三件事搜索結果的數量是否正確、點開文章詳情能否看到 OCR 全文、頁面里的封面和 CSS 是否能正常加載。只看接口返回還不夠要把頁面點擊路徑也走一遍。7.2 常見問題排查表問題現象常見原因檢查方式處理建議搜索時報no such table: fts_articles數據庫初始化時沒有執行 FTS5 建表語句查看schema.sql是否包含CREATE VIRTUAL TABLE用 SQLite 工具打開 db 查表重新執行python init_db.py或手動補建 FTS5 表和觸發器搜索返回結果為空MATCH 查詢詞被 FTS5 當成語法關鍵字打印實際傳給 SQLite 的 search_query對用戶輸入做轉義或限制只能使用普通短語查詢中文搜索不到結果FTS5 默認分詞器不切分中文用SELECT * FROM fts_articles WHERE fts_articles MATCH 測試驗證導入時額外生成分詞字段或遷移到 PostgreSQL導入時報 UNIQUE 約束失敗同一期次被重復導入查詢issues表確認是否已有相同magazine_id issue_number調整導入腳本使用INSERT OR IGNORE或先查詢再插入啟動后數據庫被鎖SQLite 默認不開啟 WAL多個進程同時寫入會沖突查看日志中是否有database is locked連接后執行PRAGMA journal_modeWAL; PRAGMA busy_timeout5000;封面圖片不顯示文件路徑或文件名大小寫不一致在瀏覽器打開圖片 URL看是否 404統一使用小寫文件名路徑用url_for生成7.3 一個完整錯誤日志排查示例下面是一個真實啟動時容易遇到的錯誤sqlite3.OperationalError: no such table: fts_articles這個錯誤說明 FTS5 虛擬表沒有創建。可能是在init_db.py之前就執行了其他腳本也可能先前的schema.sql里漏掉了 FTS5 部分。排查路徑檢查data/legacy.db是否已經存在如果存在可能是舊版本。打開 SQLite 命令行執行.tables確認有沒有fts_articles。如果表不存在先備份現有數據再確認schema.sql中有 CREATE VIRTUAL TABLE