# CaiWuXiTong 本地部署说明

## 项目概况
- 基于 [Akaunting](https://akaunting.com) 二次开发的"江陵"版财务系统
- 技术栈：PHP 8.3 + Laravel + Vue + Apache + MySQL 8.0
- 访问端口：**18088**

## 文件清单（本地部署新增）
| 文件 | 作用 |
|------|------|
| `docker-compose.local.yml` | 本地 compose：app + mysql，bridge 网络 |
| `deploy/Dockerfile.local` | 本地 Dockerfile：基于原 Dockerfile，增加 composer/npm 依赖安装 |
| `deploy/local-init.sh` | 一键构建+启动+初始化脚本 |
| `runtime/.env` | 应用环境配置（挂载到容器 `/var/www/html/.env`） |
| `LOCAL_DEPLOY.md` | 本说明 |

> 原 `compose.jiangling.yml` / `deploy/Dockerfile` 未改动，保留团队主线一致性。

## 一键部署
```bash
cd CaiWuXiTong_src
bash deploy/local-init.sh
```

## 手动步骤
```bash
# 1. 启动
docker compose -f docker-compose.local.yml up -d --build

# 2. 初始化数据库与管理员
docker compose -f docker-compose.local.yml exec app \
    php artisan install --no-interaction \
        --db-host=mysql --db-name=akaunting \
        --db-username=akaunting --db-password=akaunting123 \
        --admin-email=admin@company.com --admin-password=admin123 \
        --locale=zh-CN

# 3. 访问
open http://127.0.0.1:18088
```

## 登录信息
- **地址**：http://127.0.0.1:18088
- **邮箱**：`admin@company.com`
- **密码**：`admin123`

## 常用维护命令
```bash
# 查看日志
docker compose -f docker-compose.local.yml logs -f app

# 重启
docker compose -f docker-compose.local.yml restart app

# 进入容器
docker compose -f docker-compose.local.yml exec app bash

# 进入 MySQL
docker compose -f docker-compose.local.yml exec mysql mysql -uakaunting -pakaunting123 akaunting

# 清缓存
docker compose -f docker-compose.local.yml exec app php artisan optimize:clear

# 重新迁移
docker compose -f docker-compose.local.yml exec app php artisan migrate --force

# 停止 / 启动 / 销毁
docker compose -f docker-compose.local.yml stop
docker compose -f docker-compose.local.yml start
docker compose -f docker-compose.local.yml down          # 仅停容器
docker compose -f docker-compose.local.yml down -v       # 同时删除数据卷（会清空数据库！）
```

## 端口映射
| 服务 | 宿主机端口 | 容器端口 |
|------|-----------|----------|
| Akaunting (Apache) | 18088 | 18088 |
| MySQL | 13306 | 3306 |

## 数据卷
- `jiangling_storage` —— 应用上传文件、日志、缓存
- `jiangling_mysql` —— MySQL 数据文件

## 注意事项
- 修改 `.env` 后需重启 app 容器：`docker compose -f docker-compose.local.yml restart app`
- 修改源码后需重新构建：`docker compose -f docker-compose.local.yml up -d --build app`
- 此本地配置仅供开发/测试，**不要用于生产**（密码弱、APP_DEBUG=true）

## 重要：DB_PREFIX 必须用短前缀
项目某个模块迁移创建了较长的唯一索引
（`ec_stores_company_id_channel_id_external_id_deleted_at_unique`，60 字符），
MySQL 标识符上限 64 字符，所以 `DB_PREFIX` 必须 ≤ 4 字符。本部署用 `a_`。

⚠️ **不要**让 `php artisan install` 自动生成前缀（它默认用 `str_random(3) . '_'` 是 4 字符，
刚好不超），但**首次 install 必须显式传 `--db-prefix=a_`** 或其他 ≤4 字符值，
否则可能随机到 5+ 字符前缀触发 1059 错误。

## 重置数据（清空重来）
```bash
docker compose -f docker-compose.local.yml exec mysql \
    mysql -uroot -prootpass -e "DROP DATABASE IF EXISTS akaunting; CREATE DATABASE akaunting CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

docker compose -f docker-compose.local.yml exec app php artisan install --no-interaction \
    --db-host=mysql --db-name=akaunting \
    --db-username=akaunting --db-password=akaunting123 \
    --db-prefix=a_ \
    --company-name="本地测试公司" --company-email=admin@company.com \
    --admin-email=admin@company.com --admin-password=admin123 \
    --locale=zh-CN
```

## 部署中遇到并已解决的问题（备忘）
1. **Docker Hub 国内访问**：daemon.json 配置 `https://docker.1ms.run` 镜像源
2. **containerd snapshotter 导致 binary 全 0 字节**：在 Docker Desktop 设置里关闭 `UseContainerdSnapshotter`，改用 overlay2
3. **apt 交互卡住**：Dockerfile 加 `DEBIAN_FRONTEND=noninteractive` + `/etc/apt/apt.conf.d/99force-conf`
4. **deb.debian.org 不稳**：Dockerfile 切到清华 Debian 镜像
5. **node-sass 需要 python/make/g++**：Dockerfile 补装 `python3 make g++`
6. **npm run prod OOM**：改用 `npm run dev` + `NODE_OPTIONS=--max-old-space-size=2048`
7. **ec_stores 索引名超长**：用 `--db-prefix=a_`（见上）