准备工作
需提前安装指定工具，所有下载/命令均为可直接执行内容：
- 操作系统：任意Windows/macOS/Linux
- Python 3.10+：Windows下载地址https://www.python.org/ftp/python/3.10.11/python-3.10.11-amd64.exe；macOS执行brew install python@3.10；Linux执行apt install python3.10
- FFmpeg：Windows下载地址https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-n6.0-latest-win64-gpl-6.0.zip，解压后将bin文件夹加入系统环境变量；macOS执行brew install ffmpeg；Linux执行apt install ffmpeg
- Python依赖包：需安装fastapi、uvicorn、pydub、python-multipart
系统搭建步骤
步骤1：初始化项目环境
打开终端执行以下命令，创建项目并配置虚拟环境：
```bash
mkdir archive_audio_system && cd archive_audio_system
python -m venv venv
Windows激活虚拟环境：venv\Scripts\activate
macOS/Linux激活虚拟环境：source venv/bin/activate
pip install fastapi uvicorn[standard] pydub python-multipart
```
步骤2：编写核心代码
在项目文件夹下创建main.py文件，复制以下完整代码（无需修改，直接运行）：
```python
from fastapi import FastAPI, UploadFile, File, HTTPException
from pydantic import BaseModel
import sqlite3
import os
from datetime import datetime
import shutil
初始化FastAPI应用
app = FastAPI(title="档案音频管理系统")
系统配置
UPLOAD_DIR = "./audio_files" 音频存储目录
DB_PATH = "./archive.db" 数据库文件路径
初始化存储目录和数据库
os.makedirs(UPLOAD_DIR, exist_ok=True)
def init_db():
conn = sqlite3.connect(DB_PATH)
cursor = conn.cursor()
创建音频档案表
cursor.execute("""
CREATE TABLE IF NOT EXISTS audio_files (
id INTEGER PRIMARY KEY AUTOINCREMENT,
filename TEXT NOT NULL,
file_path TEXT NOT NULL,
duration REAL,
upload_time DATETIME DEFAULT CURRENT_TIMESTAMP,
tags TEXT
)
""")
conn.commit()
conn.close()
init_db()
上传请求参数模型
class AudioUploadRequest(BaseModel):
tags: str = "" 音频标签，便于后续检索
音频上传接口
@app.post("/api/upload-audio")
async def upload_audio(file: UploadFile = File(...), request: AudioUploadRequest):
验证音频格式（仅支持4种常用格式）
if not file.filename.lower().endswith(('.mp3', '.wav', '.flac', '.m4a')):
raise HTTPException(status_code=400, detail="仅支持mp3、wav、flac、m4a格式")
保存音频文件到本地
file_path = os.path.join(UPLOAD_DIR, file.filename)
with open(file_path, "wb") as buffer:
shutil.copyfileobj(file.file, buffer)
计算音频时长（单位：秒）
try:
from pydub import AudioSegment
audio = AudioSegment.from_file(file_path)
duration = round(len(audio) / 1000, 2)
except Exception as e:
raise HTTPException(status_code=500, detail=f"获取音频时长失败：{str(e)}")
写入数据库
conn = sqlite3.connect(DB_PATH)
cursor = conn.cursor()
cursor.execute("""
INSERT INTO audio_files (filename, file_path, duration, tags)
VALUES (?, ?, ?, ?)
""", (file.filename, file_path, duration, request.tags))
conn.commit()
conn.close()
return {"code": 200, "message": "上传成功", "data": {"id": cursor.lastrowid, "duration": duration}}
按标签查询音频接口
@app.get("/api/query-audio")
async def query_audio(tag: str = None):
conn = sqlite3.connect(DB_PATH)
cursor = conn.cursor()
若提供标签则模糊检索，否则返回全部音频
if tag:
cursor.execute("SELECT FROM audio_files WHERE tags LIKE ?", (f"%{tag}%",))
else:
cursor.execute("SELECT FROM audio_files")
格式化查询结果
results = cursor.fetchall()
audio_list = []
for row in results:
audio_list.append({
"id": row[0],
"filename": row[1],
"duration": row[3],
"upload_time": row[4],
"tags": row[5]
})
conn.close()
return {"code": 200, "data": audio_list}
启动服务
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000, reload=True)
```
步骤3：启动系统并访问
激活虚拟环境后，执行以下命令启动服务：
```bash
python main.py
```
服务启动成功后，终端会显示：Uvicorn running on http://0.0.0.0:8000，此时打开浏览器访问http://localhost:8000/docs，即可看到系统的交互式操作界面。
核心操作指南（必看）
① 上传音频档案
在/docs页面找到/api/upload-audio接口，点击「Try it out」；点击「Choose File」选择本地音频，在「tags」输入框填写分类标签（如「会议录音」「培训音频」）；点击「Execute」，等待返回code=200即为上传成功，单文件建议不超过100MB，避免上传超时。
② 按标签检索音频
找到/api/query-audio接口，点击「Try it out」；在「tag」输入框填写要检索的关键词（如「会议」）；点击「Execute」，下方将返回所有匹配标签的音频档案，包含ID、文件名、时长、上传时间等信息。
③ 可选扩展配置
若需调整服务端口，修改启动代码中的port=8000为未被占用的端口（如8080）；若需支持更多音频格式，在上传验证的后缀列表中添加对应格式；若需批量上传，可在upload接口中添加多文件处理逻辑。
局域网共享访问（可选）
若需让同局域网的其他设备访问，修改启动代码中的host为当前设备的局域网IP（如192.168.1.105）：
```python
uvicorn.run(app, host="192.168.1.105", port=8000, reload=True)
```
Windows需在防火墙中开放8000端口，macOS/Linux无需额外配置，局域网内其他设备通过http://192.168.1.105:8000/docs即可访问系统。
