廊坊档案软件从零开发与部署全流程实操指南

一、基础环境搭建与依赖初始化

在开始构建廊坊档案软件之前，必须准备好标准化的运行环境。本指南基于Ubuntu 22.04 LTS系统，采用Python作为后端开发语言，Vue 3作为前端框架，通过Docker进行容器化部署，确保零门槛落地。

1. 安装Docker及Docker Compose

首先执行以下命令更新系统源并安装Docker引擎，这是构建容器化环境的基础：

``` sudo apt-get update sudo apt-get install -y docker.io docker-compose sudo systemctl start docker sudo systemctl enable docker ```

2. 创建项目目录结构

在终端执行以下命令，创建清晰的项目分层目录，便于后续代码管理：

``` mkdir -p langfang-archives/{backend,frontend,nginx} cd langfang-archives ```

3. 后端环境初始化

进入backend目录，创建Python虚拟环境并安装核心依赖包。这里使用FastAPI作为高性能Web框架，SQLAlchemy用于ORM数据库操作：

``` cd backend python3 -m venv venv source venv/bin/activate pip install fastapi uvicorn sqlalchemy python-multipart aiofiles ```

在backend目录下创建requirements.txt文件，锁定版本以防依赖冲突，内容如下：

``` fastapi==0.104.1 uvicorn==0.24.0 sqlalchemy==2.0.23 python-multipart==0.0.6 aiofiles==23.2.1 pydantic==2.5.0 ```

二、后端核心代码实现

后端主要负责档案数据的存储、检索以及文件的上传下载。我们将构建一个符合廊坊地区档案分类标准的轻量级API。

1. 数据库模型设计

在backend目录下创建database.py，编写数据库连接与模型定义。这里使用SQLite作为演示数据库，生产环境可替换为PostgreSQL：

``` from sqlalchemy import create_engine, Column, Integer, String, DateTime, Text from sqlalchemy.ext.declarative import declarative_base from sqlalchemy.orm import sessionmaker import datetime SQLALCHEMY_DATABASE_URL = "sqlite:///./langfang_archives.db" engine = create_engine(SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False}) SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine) Base = declarative_base() class Archive(Base): __tablename__ = "archives" id = Column(Integer, primary_key=True, index=True) title = Column(String(200), nullable=False, index=True) category_code = Column(String(50), nullable=False) 廊坊档案分类码 dept = Column(String(100)) 归档部门 description = Column(Text) file_path = Column(String(500)) created_at = Column(DateTime, default=datetime.datetime.now) Base.metadata.create_all(bind=engine) ```

2. API业务逻辑编写

在backend目录下创建main.py，实现档案的增删改查接口。特别注意UPLOAD_DIR的配置，需确保容器内有写权限：

``` from fastapi import FastAPI, UploadFile, File, Depends, HTTPException from fastapi.staticfiles import StaticFiles from fastapi.middleware.cors import CORSMiddleware from sqlalchemy.orm import Session from typing import List import shutil import os from database import SessionLocal, Archive, engine, Base app = FastAPI(title="Langfang Archives API") 允许跨域访问 app.add_middleware( CORSMiddleware, allow_origins=[""], allow_credentials=True, allow_methods=[""], allow_headers=[""], ) 挂载静态文件目录 UPLOAD_DIR = "uploads" if not os.path.exists(UPLOAD_DIR): os.makedirs(UPLOAD_DIR) app.mount("/static", StaticFiles(directory=UPLOAD_DIR), name="static") def get_db(): db = SessionLocal() try: yield db finally: db.close() @app.post("/api/archives/") async def create_archive(title: str, category_code: str, dept: str, description: str = "", file: UploadFile = File(...), db: Session = Depends(get_db)): file_location = f"{UPLOAD_DIR}/{file.filename}" with open(file_location, "wb+") as file_object: shutil.copyfileobj(file.file, file_object) db_archive = Archive( title=title, category_code=category_code, dept=dept, description=description, file_path=file_location ) db.add(db_archive) db.commit() db.refresh(db_archive) return {"message": "档案归档成功", "id": db_archive.id} @app.get("/api/archives/", response_model=List[dict]) async def list_archives(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)): archives = db.query(Archive).offset(skip).limit(limit).all() results = [] for arc in archives: results.append({ "id": arc.id, "title": arc.title, "category_code": arc.category_code, "dept": arc.dept, "created_at": arc.created_at, "file_path": arc.file_path }) return results ```

三、前端界面开发

前端使用Vue 3配合Element Plus组件库，构建简洁的档案录入与查询界面。

1. 项目初始化

回到项目根目录，创建Vue项目并安装Element Plus：

``` cd .. npm create vite@latest frontend -- --template vue cd frontend npm install npm install element-plus axios ```

2. 配置代理与组件引入

修改frontend/vite.config.js，添加代理配置解决跨域问题：

``` import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], server: { proxy: { '/api': 'http://localhost:8000', '/static': 'http://localhost:8000' } } }) ```

3. 编写主界面代码

修改frontend/src/App.vue，实现档案上传表单和列表展示功能：

``` ```

同时修改frontend/src/main.js引入Element Plus样式：

``` import { createApp } from 'vue' import './style.css' import App from './App.vue' import ElementPlus from 'element-plus' import 'element-plus/dist/index.css' createApp(App).use(ElementPlus).mount('app') ```

四、容器化部署配置

为了实现一键启动，我们需要编写Dockerfile和docker-compose.yml文件。

1. 后端Dockerfile

在backend目录下创建Dockerfile：

``` FROM python:3.9-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] ```

2. 前端Dockerfile

在frontend目录下创建Dockerfile，利用多阶段构建减小镜像体积：

``` FROM node:16-alpine as build-stage WORKDIR /app COPY package.json ./ RUN npm install COPY . . RUN npm run build FROM nginx:stable-alpine as production-stage COPY --from=build-stage /app/dist /usr/share/nginx/html EXPOSE 80 CMD ["nginx", "-g", "daemon off;"] ```

3. Nginx反向代理配置

在项目根目录的nginx文件夹下创建nginx.conf，用于转发API请求：

``` events { worker_connections 1024; } http { include /etc/nginx/mime.types; default_type application/octet-stream; server { listen 80; server_name localhost; location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://backend:8000; } location /static/ { proxy_pass http://backend:8000; } } } ```

4. Docker Compose编排

在项目根目录下创建docker-compose.yml，这是启动整个系统的核心配置：

``` version: '3.8' services: backend: build: ./backend volumes: - ./backend/uploads:/app/uploads ports: - "8000:8000" frontend: build: context: ./frontend dockerfile: Dockerfile ports: - "80:80" depends_on: - backend volumes: - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro ```

五、系统启动与验证

所有配置文件已就绪，现在进行最终的构建与启动操作。

1. 构建并启动服务

在项目根目录langfang-archives下执行以下命令，Docker会自动拉取镜像、构建代码并启动容器：

``` docker-compose up -d --build ```

2. 验证服务状态

执行docker-compose ps查看容器状态，确保所有服务的State均为Up。如果后端启动失败，请检查backend目录下的uploads文件夹权限，确保容器内可写。

3. 访问系统

打开浏览器，访问服务器的IP地址（如果是本地则访问http://localhost）。你将看到廊坊档案管理系统的主界面。尝试填写“档案标题”，选择“分类代码”，上传一个测试文件并点击提交。成功后，下方列表会即时显示刚才归档的档案信息，点击“下载”可获取文件。

4. 数据持久化说明

在本配置中，数据库文件langfang_archives.db和上传的文件均通过Docker Volume挂载在宿主机目录下。即使删除容器重新运行，数据依然保留。备份时，只需备份backend目录下的langfang_archives.db和uploads文件夹即可。